Yaowei Zheng
d4faee3a1e
Branch-length batch covering tooling, the model layer, the Web App and the public surfaces. Highlights: - Changelog: a per-release `changelog/<version>/` tree, grouped by the surface each change touches, with a root CHANGELOG.md holding one line per release. - Dev startup: `scripts/dev-prebuild.mjs` serializes the skills+core prebuild behind a lock and keeps `pnpm install` current; `pnpm dev` runs server+web together. - AgentHub 0.3.3 -> 0.4.0: OmniMessage complete payloads carry one opaque `fidelity` object in place of item-level `signature`/`phase`, threaded verbatim through Trace, replay and resume; malformed classification adapted to the new error types. - Model layer: a model is always referenced by an explicit `(provider, model_id)` pair. The provider is never inferred, guessed or defaulted -- both the catalog inference and the unique-match config resolution are gone, and CLI, SDK, server routes and run_subagent all require the complete pair. Catalog gains the Qwen Token Plan, Qwen Pay-As-You-Go and Fireworks AI gateways, plus an expanded OpenRouter group. - Web App: catalog preset sync and per-group speed test on the Models page, positional slash commands, a markdown renderer, skill-library update reminders, and a vertically centred draft page whose upward menus size themselves to the room available. - Public surfaces: restructured READMEs, the penguin.ooo landing site and blog, refreshed benchmark results for both suites, and the demo videos playing on the landing page. Includes the fixes from a full review of the branch: 23 confirmed findings, among them a provider-inference bug that could send one vendor's API key to another vendor's endpoint, and an Escape handler that destroyed the composer's contents unrecoverably. Verified on the branch head: pnpm test (1127 passing, 7 packages), pnpm typecheck and pnpm format:check clean, Playwright e2e 14/14.
146 lines
6.0 KiB
Markdown
146 lines
6.0 KiB
Markdown
---
|
|
title: CLI Reference
|
|
description: Complete reference for the penguin command, its subcommands, and options.
|
|
---
|
|
|
|
The CLI ships as the npm package `@prismshadow/penguin-cli`; the command is `penguin`. Running bare `penguin` prints help; `-v, --version` prints the version. A `.env` file in the working directory is loaded automatically on startup.
|
|
|
|
## Global conventions
|
|
|
|
- Model references: a model's identity is always the `(provider, model_id)` pair. `--model-id` takes the upstream model id and `--provider` the group it belongs to; the provider is never inferred, guessed, or defaulted. On `run` / `chat` the pair as a whole is optional — pass both to pick a model, or neither to use the Project's default model — but passing one without the other is an error.
|
|
- Data root: `--root <dir>` overrides the data root directory. Priority: `--root` > the `PENGUIN_HOME` env var > `~/.penguin/data`.
|
|
|
|
## penguin run
|
|
|
|
Send a single message, execute one Task, then exit. If the Task aborted, the exit code is non-zero, so scripts / CI can check it.
|
|
|
|
```bash
|
|
penguin run -m "Summarize the code structure of this directory"
|
|
```
|
|
|
|
| Option | Description |
|
|
| --- | --- |
|
|
| `-m, --message <message>` | Required; the message to send |
|
|
| `--model-id <id>` | Upstream id of the model to use; requires `--provider`. Omit both to use the Project's default model |
|
|
| `--provider <group>` | Provider group of the model; required whenever `--model-id` is given |
|
|
| `--project-id <id>` | Project to use |
|
|
| `--agent-id <id>` | Agent to use |
|
|
| `--workspace <path>` | Workspace directory; defaults to the current directory and must exist |
|
|
| `--approve <mode>` | Approval mode, see below |
|
|
|
|
## penguin chat
|
|
|
|
Interactive REPL; each input line starts a Task. Takes the same options as `run` (minus `-m, --message`), plus:
|
|
|
|
| Option | Description |
|
|
| --- | --- |
|
|
| `--resume [sessionId]` | Resume a Session; without an id, resumes the Agent's latest Session |
|
|
|
|
With `--resume`, the Workspace and model are locked by the original Session and cannot be overridden via `--workspace` / `--model-id` / `--provider`. On exit, a copy-pastable `penguin chat --resume <sessionId>` command is printed.
|
|
|
|
In-REPL commands:
|
|
|
|
| Input | Behavior |
|
|
| --- | --- |
|
|
| `/compact` | Proactively compact the current context |
|
|
| `/exit`, `/quit` | Quit |
|
|
|
|
Ctrl-C is state-dependent:
|
|
|
|
| State | Behavior |
|
|
| --- | --- |
|
|
| Awaiting tool approval | Deny that tool call |
|
|
| Task running | Abort the current Task and return to input |
|
|
| Input buffer non-empty | Clear the current input |
|
|
| Idle with empty buffer | Show an exit confirmation (y/N) |
|
|
|
|
## Approval modes (--approve)
|
|
|
|
| Mode | Behavior |
|
|
| --- | --- |
|
|
| `allow-all` | Auto-approve every tool call (default) |
|
|
| `deny-all` | Auto-reject every tool call |
|
|
| `read-only` | Auto-approve read-only tools; prompt for the rest |
|
|
| `always-ask` | Prompt for every tool call |
|
|
|
|
At an interactive prompt, `y` / `yes` approves and `n` / `no` denies; a bare Enter defaults to approve.
|
|
|
|
## penguin config
|
|
|
|
Manages a Project's model configuration, per-Agent vault environment variables, and the UI language. Except for `lang`, all subcommands below accept `--project-id <id>` (defaults to the default Project) and `--root <dir>`.
|
|
|
|
### model add
|
|
|
|
Add or update a model entry:
|
|
|
|
```bash
|
|
penguin config model add --provider deepseek --model-id deepseek-v4-pro --api-key sk-... --set-default
|
|
```
|
|
|
|
| Option | Description |
|
|
| --- | --- |
|
|
| `--model-id <id>` | Required; the upstream model id |
|
|
| `--provider <group>` | Required; the provider group the entry belongs to. It is never derived from the model id: gateways resell vendor models under their upstream ids, so a guessed group would write the credential onto another vendor's endpoint. Use `custom` for any endpoint outside the built-in groups. |
|
|
| `--api-key <key>` | API key, stored inline in the Project's hidden `.project_config.toml` |
|
|
| `--base-url <url>` | Custom endpoint base URL |
|
|
| `--context-window <n>` | Context window size |
|
|
| `--client-type <type>` | Client protocol type |
|
|
| `--vision` / `--no-vision` | Mark vision input as supported / unsupported |
|
|
| `--price-cache-read <n>` | Cache-read price |
|
|
| `--price-cache-write <n>` | Cache-write price |
|
|
| `--price-output <n>` | Output price |
|
|
| `--set-default` | Also set as the default model |
|
|
|
|
### model default / model vision / model list
|
|
|
|
```bash
|
|
penguin config model default --model-id <id> --provider <group>
|
|
penguin config model vision --model-id <id> --provider <group>
|
|
penguin config model list
|
|
```
|
|
|
|
- `model default` sets the Project's default model; `model vision` sets the vision proxy model. Both require `--model-id` and `--provider`, and the reference must already exist in the model list.
|
|
- `model list` lists configured models; the default model is marked with `*`.
|
|
|
|
### vault
|
|
|
|
Per-Agent environment variable store, written to `agent_state/.vault.toml`. Values are injected into tool subprocess environments only — never into the model context.
|
|
|
|
```bash
|
|
penguin config vault set --key GITHUB_TOKEN --value ghp_xxx
|
|
penguin config vault list
|
|
penguin config vault remove --key GITHUB_TOKEN
|
|
```
|
|
|
|
| Subcommand | Options |
|
|
| --- | --- |
|
|
| `vault set` | `--key <name>` (required), `--value <value>` (required), `[--agent-id <id>]` |
|
|
| `vault list` | `[--agent-id <id>]` |
|
|
| `vault remove` | `--key <name>` (required), `[--agent-id <id>]` |
|
|
|
|
### lang
|
|
|
|
```bash
|
|
penguin config lang en
|
|
```
|
|
|
|
Sets the CLI UI language (`en` or `zh`) by writing `PENGUIN_LANG` into the shell startup file.
|
|
|
|
## penguin server / penguin web
|
|
|
|
Two entry points into the same service process: `server` runs headless; `web` additionally waits for readiness, prints the URL, and opens the browser.
|
|
|
|
```bash
|
|
penguin web
|
|
```
|
|
|
|
| Option | Description |
|
|
| --- | --- |
|
|
| `--port <port>` | Listen port, default 7364 |
|
|
| `--host <host>` | Listen host, default 127.0.0.1 |
|
|
| `--no-open` | `web` only: do not open the browser |
|
|
|
|
Port / host priority: command-line option > the `PORT` / `HOST` env vars (including `.env`) > defaults.
|
|
|
|
See also: [Configuration Reference](/configuration), [Models & Providers](/models).
|