Pi Agent CLI Reference Manual
The following is a reference for common Pi Agent command-line parameters.
Mode Options
The following parameters control the running mode of Pi Agent. If not specified, it enters the interactive interface by default.
| Parameter | Description | Example |
|---|---|---|
| (Default) | Interactive mode, terminal TUI interface | pi |
| -p, --print | Print mode, exits after outputting the result | pi -p "summarize code" |
| --mode json | JSON mode, all events output as JSON lines | pi --mode json -p "summarize" |
| --mode rpc | RPC mode, stdin/stdout JSONL protocol | pi --mode rpc |
| --export <input> [output] | Export session to HTML; output path can be omitted | pi --export abc123 session.html |
Model Options
The following parameters are used to specify the provider, model, and reasoning level, suitable for temporary switching without modifying configuration files.
| Parameter | Description | Example |
|---|---|---|
| --provider name | Specify AI provider | pi --provider anthropic |
| --model pattern | Model ID, supports provider/id and :thinking formats | pi --model openai/gpt-4o pi --model sonnet:high |
| --api-key key | Pass the API Key directly, with the highest priority; replace the example value with your own Key | pi --api-key sk-ant-api03-xxxx |
| --thinking level | Reasoning level: off/minimal/low/medium/high/xhigh/max | pi --thinking high |
| --models patterns | Comma-separated model list, limits Ctrl+P cycling | pi --models "claude-*,gpt-4o" |
| --list-models | List all available models | pi --list-models |
Session Options
The following parameters determine which session is used in this run and where session files are saved.
| Parameter | Description | Example |
|---|---|---|
| -c, --continue | Continue the most recent session | pi -c |
| -r, --resume | Browse and select a historical session | pi -r |
| --session path|id | Use a specified session file or UUID | pi --session abc123 |
| --fork path|id | Fork a new session from the specified session | pi --fork abc123 |
| --session-dir dir | Custom session storage directory; the default directory is ~/.pi/agent/sessions/, this parameter temporarily replaces it | pi --session-dir .pi/sessions |
| --no-session | Temporary mode, does not save sessions | pi --no-session |
| -n, --name name | Set session display name | pi --name "Refactor authentication module" |
Tool Options
The following parameters control the availability of built-in tools, used to tighten permissions or for pure conversation.
| Parameter | Description | Example |
|---|---|---|
| -t, --tools list | Whitelist specified tools, comma-separated | pi --tools read,bash,edit,write |
| -xt, --exclude-tools list | Disable specified tools, comma-separated | pi --exclude-tools bash |
| -nbt, --no-builtin-tools | Disable all built-in tools, keep extension tools | pi --no-builtin-tools |
| -nt, --no-tools | Disable all tools, pure conversation mode | pi --no-tools |
Resource Options
The following parameters control loading of extensions, Skills, templates, and themes. Parameters with the --no- prefix are used to turn off auto-discovery.
| Parameter | Description | Example |
|---|---|---|
| -e, --extension source | Load an extension, can be used repeatedly | pi -e ./my-ext.ts -e npm:@foo/bar |
| --no-extensions | Disable extension auto-discovery | pi --no-extensions |
| --skill path | Load a Skill, can be used repeatedly | pi --skill ./my-skill |
| --no-skills | Disable Skill auto-discovery | pi --no-skills |
| --prompt-template path | Load a prompt template, can be used repeatedly | pi --prompt-template ./review.md |
| --no-prompt-templates | Disable template auto-discovery | pi --no-prompt-templates |
| --theme path | Load a theme, can be used repeatedly | pi --theme ./my-theme.json |
| --no-themes | Disable theme auto-discovery | pi --no-themes |
| -nc, --no-context-files | Disable loading of AGENTS.md/CLAUDE.md | pi -nc |
Other Options
The following parameters override behaviors such as system prompt, project trust, and help information.
| Parameter | Description | Example |
|---|---|---|
| --system-prompt text | Replace the default system prompt | pi --system-prompt "You are a Python expert" |
| --append-system-prompt text | Append to the system prompt | pi --append-system-prompt "Reply in Chinese" |
| --tui-mode | Interface mode, e.g., fullscreen; if not specified, regular mode is used | pi --tui-mode fullscreen |
| --use-theme | Specify a theme to load; only effective for the current run, does not modify configuration | pi --use-theme "dark-plus" |
| --verbose | Force display of detailed startup information | pi --verbose |
| -a, --approve | Trust project local files for this run | pi -a |
| -na, --no-approve | Do not trust project local files for this run | pi -na |
| -- | Separator; content after it is passed to prompt as-is | pi -- @notes.md Summarize this note |
| -h, --help | Display help information | pi -h |
| -v, --version | Display version number | pi -v |
-aand-naMutually exclusive; only one can be specified in the same run.
Both are limited to the current run only and will not be written to trust.json.
pi Subcommands
In addition to startup parameters, pi also provides a set of subcommands for managing extension packages and its own updates.
| Subcommand | Description |
|---|---|
| pi install <source> | Install an extension package; add -l to install locally to the project |
| pi remove <source> | Remove an installed extension package |
| pi uninstall <source> | Alias for remove, same effect |
| pi list | List installed extension packages |
| pi update | Update pi itself and extension packages; supports --self, --all, --models, --extensions, --extension <source> |
| pi config | Enable or disable various resources provided by extension packages |
Related Environment Variables
The following environment variables affect authentication, network, and terminal behavior, and can serve as supplementary configuration beyond command-line parameters.
| Variable | Purpose | Example |
|---|---|---|
| ANTHROPIC_API_KEY | Alternative method for Anthropic authentication; used when not logged in via /login subscription | sk-ant-api03-xxxx |
| HTTP_PROXY / HTTPS_PROXY | Specify a proxy server for API requests | http://127.0.0.1:7890 |
| NO_PROXY | Proxy whitelist; matched hosts do not go through the proxy | localhost,127.0.0.1 |
| COLORTERM | One of the reference values for truecolor auto-detection; if detection fails, use PI_TRUE_COLOR=1 to force enable, or configure terminal.trueColor | truecolor |
For proxies that need long-term use, it is recommended to write to~/.pi/agent/settings.jsonofhttpProxy。
This configuration only takes effect in the global configuration file; writing it at the project level.pi/settings.jsonis invalid.
File Arguments
Usage@Prefix to reference files:
$ pi @prompt.md "回答这个问题" $ pi -p @screenshot.png "图中有什么" $ pi @src/code.ts @src/test.ts "对比这两个文件"
Taking the second command as an example, the output is similar to:
The image is a screenshot of a login page, which includes a username input field, a password input field, and a login button.Other extensions