Pi Agent CLI 参考手册
以下是 Pi Agent 常用命令行参数的参考。
模式选项
以下参数控制 Pi Agent 的运行模式，不指定时默认进入交互界面。
| 参数 | 说明 | 示例 |
|---|---|---|
| （默认） | 交互模式，终端 TUI 界面 | pi |
| -p, --print | Print 模式，输出结果后退出 | pi -p "总结代码" |
| --mode json | JSON 模式，所有事件以 JSON 行输出 | pi --mode json -p "总结" |
| --mode rpc | RPC 模式，stdin/stdout JSONL 协议 | pi --mode rpc |
| --export <输入> [输出] | 导出会话为 HTML，输出路径可省略 | pi --export abc123 session.html |
模型选项
以下参数用于指定提供商、模型与推理等级，适合临时切换而不改动配置文件。
| 参数 | 说明 | 示例 |
|---|---|---|
| --provider name | 指定 AI 提供商 | pi --provider anthropic |
| --model pattern | 模型 ID，支持 provider/id 和 :thinking 格式 | pi --model openai/gpt-4o pi --model sonnet:high |
| --api-key key | 直接传入 API Key，优先级最高；示例值需替换为你自己的 Key | pi --api-key sk-ant-api03-xxxx |
| --thinking level | 推理等级：off/minimal/low/medium/high/xhigh/max | pi --thinking high |
| --models patterns | 逗号分隔的模型列表，限制 Ctrl+P 循环 | pi --models "claude-*,gpt-4o" |
| --list-models | 列出所有可用模型 | pi --list-models |
会话选项
以下参数决定本次运行使用哪个会话，以及会话文件保存在哪里。
| 参数 | 说明 | 示例 |
|---|---|---|
| -c, --continue | 继续最近的会话 | pi -c |
| -r, --resume | 浏览并选择历史会话 | pi -r |
| --session path|id | 使用指定会话文件或 UUID | pi --session abc123 |
| --fork path|id | 从指定会话分叉出新会话 | pi --fork abc123 |
| --session-dir dir | 自定义会话存储目录，默认目录为 ~/.pi/agent/sessions/，此参数用于临时替换它 | pi --session-dir .pi/sessions |
| --no-session | 临时模式，不保存会话 | pi --no-session |
| -n, --name name | 设置会话显示名称 | pi --name "重构认证模块" |
工具选项
以下参数控制内置工具的可用范围，用于收紧权限或做纯对话。
| 参数 | 说明 | 示例 |
|---|---|---|
| -t, --tools list | 白名单指定工具，逗号分隔 | pi --tools read,bash,edit,write |
| -xt, --exclude-tools list | 禁用指定工具，逗号分隔 | pi --exclude-tools bash |
| -nbt, --no-builtin-tools | 禁用所有内置工具，保留扩展工具 | pi --no-builtin-tools |
| -nt, --no-tools | 禁用所有工具，纯对话模式 | pi --no-tools |
资源选项
以下参数控制扩展、Skill、模板与主题的加载，带 --no- 前缀的参数用于关闭自动发现。
| 参数 | 说明 | 示例 |
|---|---|---|
| -e, --extension source | 加载扩展，可重复使用 | pi -e ./my-ext.ts -e npm:@foo/bar |
| --no-extensions | 禁用扩展自动发现 | pi --no-extensions |
| --skill path | 加载 Skill，可重复使用 | pi --skill ./my-skill |
| --no-skills | 禁用 Skill 自动发现 | pi --no-skills |
| --prompt-template path | 加载提示词模板，可重复使用 | pi --prompt-template ./review.md |
| --no-prompt-templates | 禁用模板自动发现 | pi --no-prompt-templates |
| --theme path | 加载主题，可重复使用 | pi --theme ./my-theme.json |
| --no-themes | 禁用主题自动发现 | pi --no-themes |
| -nc, --no-context-files | 禁用 AGENTS.md/CLAUDE.md 加载 | pi -nc |
其他选项
以下参数覆盖系统提示词、项目信任与帮助信息等行为。
| 参数 | 说明 | 示例 |
|---|---|---|
| --system-prompt text | 替换默认系统提示词 | pi --system-prompt "你是 Python 专家" |
| --append-system-prompt text | 追加到系统提示词 | pi --append-system-prompt "使用中文回复" |
| --tui-mode | 界面模式，如 fullscreen；不指定时用常规（regular）模式 | pi --tui-mode fullscreen |
| --use-theme | 指定主题加载，仅对本次运行生效，不改动配置 | pi --use-theme "dark-plus" |
| --verbose | 强制显示详细启动信息 | pi --verbose |
| -a, --approve | 本次运行信任项目本地文件 | pi -a |
| -na, --no-approve | 本次运行不信任项目本地文件 | pi -na |
| -- | 分隔符，其后内容原样传给 prompt | pi -- @notes.md 总结这份笔记 |
| -h, --help | 显示帮助信息 | pi -h |
| -v, --version | 显示版本号 | pi -v |
-a 与 -na 互斥，同一次运行只能指定其中一个。
两者的作用范围都只限于本次运行，不会写入 trust.json。
pi 子命令
除启动参数外，pi 还提供一组管理扩展包与自身更新的子命令。
| 子命令 | 说明 |
|---|---|
| pi install <source> | 安装扩展包，加 -l 安装到项目本地 |
| pi remove <source> | 移除已安装的扩展包 |
| pi uninstall <source> | remove 的别名，效果相同 |
| pi list | 列出已安装的扩展包 |
| pi update | 更新 pi 自身与扩展包，支持 --self、--all、--models、--extensions、--extension <source> |
| pi config | 启用或禁用扩展包提供的各类资源 |
相关环境变量
以下环境变量影响认证、网络与终端表现，可作为命令行参数之外的补充配置。
| 变量 | 作用 | 示例 |
|---|---|---|
| ANTHROPIC_API_KEY | Anthropic 认证的备用方式，未通过 /login 订阅登录时使用 | sk-ant-api03-xxxx |
| HTTP_PROXY / HTTPS_PROXY | 为 API 请求指定代理服务器 | http://127.0.0.1:7890 |
| NO_PROXY | 代理白名单，命中的主机不经过代理 | localhost,127.0.0.1 |
| COLORTERM | truecolor 自动检测的参考值之一；检测失败可用 PI_TRUE_COLOR=1 强制开启，或配置 terminal.trueColor | truecolor |
需要长期使用的代理建议写入 ~/.pi/agent/settings.json 的 httpProxy。
该配置仅在全局配置文件中生效，写在项目级 .pi/settings.json 中无效。
文件参数
使用 @ 前缀引用文件：
$ pi @prompt.md "回答这个问题" $ pi -p @screenshot.png "图中有什么" $ pi @src/code.ts @src/test.ts "对比这两个文件"
以第二条命令为例，输出类似：
图中是一张登录页面的截图，页面包含用户名输入框、密码输入框和一个登录按钮。