CLI 命令速查手册

前面章节分散介绍了各种命令和参数，这一章把它们整理在一起。当作案头速查用——不解释原理，只给参数、用途和怎么用。

本章基于 pi v0.84.1。

---

启动与运行模式

pi 有四种运行模式，通过命令行参数切换：

参数	说明	示例
pi（无参数）	交互模式，打开 TUI 终端界面	pi
-p, --print	Print 模式，输出结果后退出	pi -p "这段代码有什么问题"
--mode json	JSON 模式，所有事件以 JSON 行输出	pi --mode json -p "列出所有 .ts 文件"
--mode rpc	RPC 模式，通过 stdin/stdout 走 JSONL 协议	pi --mode rpc

---

模型与推理

控制用哪个提供商、哪个模型、推理深度：

参数	说明	示例
--provider <name>	指定 AI 提供商	--provider anthropic
--model <pattern>	模型 ID，支持 provider/id 和 :<thinking> 简写	--model openai/gpt-4o 或 --model sonnet:high
--api-key ***	直接传入 API Key，优先级高于环境变量	--api-key sk-xxx
--thinking <level>	推理等级：off / minimal / low / medium / high / xhigh / max	--thinking high
--models <patterns>	逗号分隔的模型列表，限制 Ctrl+P 切换范围	--models "claude-*,gpt-4o"
--list-models [search]	列出所有可用模型，可选搜索过滤	pi --list-models claude

模型简写示例：

# provider/id 完整格式
pi --model anthropic/claude-sonnet-4-20250514

# :thinking 后缀简写
pi --model sonnet:high          # 相当于 claude-sonnet-4 + 高推理
pi --model sonnet:medium         # 同款模型 + 中等推理
pi --model opus:max              # claude-opus-4 + 最高推理

---

会话管理

控制会话的保存、恢复、分叉和命名：

参数	说明	示例
-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 --session-dir .pi/sessions
--no-session	临时模式，不保存会话	pi --no-session -p "快速一问"
-n, --name <name>	设置会话显示名称	pi --name "重构认证模块"

---

工具控制

白名单、黑名单或完全禁止工具执行：

参数	说明	示例
-t, --tools <list>	白名单指定工具，逗号分隔	--tools read,bash,edit,write
-xt, --exclude-tools <list>	禁用指定工具，逗号分隔	--exclude-tools bash
-nbt, --no-builtin-tools	禁用所有内置工具，保留扩展工具	pi --no-builtin-tools
-nt, --no-tools	禁用所有工具，纯对话模式	pi --no-tools "解释这段代码"

内置工具有七个：read、bash、edit、write、grep、find、ls。-nbt 把它们全关掉但保留安装的扩展里注册的工具；-nt 连扩展工具也一起关。

---

资源加载

控制 extension、skill、模板、主题等资源的加载：

参数	说明	示例
-e, --extension <source>	加载扩展，可重复使用	-e ./my-ext.ts -e npm:@foo/bar
--no-extensions	禁用扩展自动发现	pi --no-extensions
--skill <path>	加载 Skill，可重复使用	--skill ./my-skill
--no-skills	禁用 Skill 自动发现	pi --no-skills
--prompt-template <path>	加载提示词模板，可重复使用	--prompt-template ./review.md
--no-prompt-templates	禁用模板自动发现	pi --no-prompt-templates
--theme <path>	加载主题，可重复使用	--theme ./my-theme.json
--no-themes	禁用主题自动发现	pi --no-themes
-nc, --no-context-files	禁用 AGENTS.md / CLAUDE.md 加载	pi -nc

组合 --no-* 和显式加载可以精确控制 pi 只加载你指定的资源：

pi --no-extensions -e ./my-extension.ts

---

提示词与行为

参数	说明	示例
--system-prompt <text>	替换默认系统提示词	--system-prompt "你是 Python 专家"
--append-system-prompt <text>	追加到系统提示词末尾	--append-system-prompt "用中文回复"
--verbose	强制显示详细启动信息	pi --verbose
-a, --approve	本次运行信任项目本地文件	pi -a
-na, --no-approve	本次运行不信任项目本地文件	pi -na
-h, --help	显示帮助信息	pi -h
-v, --version	显示版本号	pi -v

--system-prompt 是替换，--append-system-prompt 是追加。两者可以一起用——先用 --system-prompt 换掉默认的，再用 --append-system-prompt 把额外指令粘在末尾。

---

包管理命令

pi 内置了一套包管理子命令，管理 extensions、skills 等资源的安装和更新：

命令	说明	示例
pi install <source> [-l]	安装包，-l 表示安装到项目本地	pi install pi-skills
pi remove <source> [-l]	移除包	pi remove pi-skills -l
pi uninstall <source> [-l]	remove 的别名	pi uninstall @org/extension
pi update [source|self|pi]	更新 pi 自身或指定包	pi update self
pi update --all	更新 pi 和所有包，同步 git refs	pi update --all
pi update --extensions	只更新包，同步 git refs	pi update --extensions
pi update --models	只刷新模型目录	pi update --models
pi update --self	只更新 pi 自身	pi update --self
pi list	列出已安装的包	pi list
pi config	启用/禁用包中的资源	pi config

---

文件引用

@ 前缀把文件内容注入到消息里：

# 引用文本文件
pi @prompt.md "回答这个问题"

# 引用图片（pi 会发给模型识别）
pi -p @screenshot.png "图里有什么"

# 引用多个文件
pi @src/code.ts @src/test.ts "对比这两个文件"

# 文件引用 + 文本 prompt 一起
pi @README.md "把不准确的描述都改掉"

在交互模式下，输入 @ 会自动弹出模糊搜索来选文件。

---

常用命令组合

以下是把多个参数组合起来的典型用法：

只读审查模式——只让 pi 看代码不让它改：

pi --tools read,grep,find,ls -p "审查 src/ 目录下的代码质量"

本地模型一段式——用 llama.cpp 跑本地模型，不联网：

pi --provider llamacpp --model llama3.1-8b -p "这段函数有什么问题" @src/bug.ts

离线模式 + 指定扩展——关掉自动加载，只启用你指定的：

pi --no-extensions --no-skills --no-context-files -e ./my-tool.ts

命名的一次性任务——用完就关，但会话有名字方便后面找回：

pi --name "发布前检查" -p "检查 package.json 版本号和 changelog"

高推理解决复杂问题：

pi --thinking max "这个并发问题已经排查了两天，帮我彻底分析根因"
pi --model opus:max "重构整个数据层的架构设计"

代理环境启动——在中国大陆需要走代理访问 API：

# 先设置代理再启动
HTTPS_PROXY=http://127.0.0.1:7890 pi

---

交互模式下的斜杠命令

在 TUI 界面输入 / 打开命令补全。以下按功能分组列出所有内置命令。

账户与认证

命令	功能
/login	登录 AI 提供商，支持 OAuth 和 API Key 两种方式
/logout	登出，清除当前提供商凭证

模型管理

命令	功能
/model	打开模型选择器，切换当前模型
/scoped-models	管理 Ctrl+P 可用模型列表，开启/关闭特定模型
/llama	管理 llama.cpp 本地模型——下载、加载、卸载

会话管理

命令	功能
/new	开始新会话
/resume	浏览并恢复历史会话
/name <名称>	设置当前会话显示名称
/session	查看会话文件路径、ID、消息数、token 数和费用
/tree	打开会话树浏览器，跳到任意历史节点继续
/fork	从历史消息分叉出新会话
/clone	克隆当前活跃分支到新会话
/compact [提示]	手动压缩上下文，可带自定义指令

内容操作

命令	功能
/copy	复制 AI 最后一条回复到剪贴板
/export [文件]	导出会话为 HTML 或 JSONL 文件
/import <文件>	导入 JSONL 会话文件并恢复
/share	上传为 GitHub Gist，生成可分享链接

设置与管理

命令	功能
/settings	打开设置面板，调整常用配置项
/trust	保存项目信任决策，下次启动不再问
/reload	热重载所有资源——快捷键、扩展、skills、模板、主题、上下文文件
/hotkeys	显示所有键盘快捷键列表
/changelog	显示版本更新日志
/quit	退出 pi

隐式命令

这些不是通过 / 前缀，而是通过特殊前缀触发的：

前缀	功能	示例
!	执行 shell 命令，输出发送给 AI	!npm test
!!	执行 shell 命令，输出不发送给 AI	!!cat ~/.zshrc

扩展注册的命令

Extensions 和 skills 会自动注册命令：

类型	格式	示例
扩展命令	/命令名	/stats（如果某个扩展注册了 stats 命令）
Skill 命令	/skill:技能名	/skill:brave-search
提示词模板	/模板名	/review（如果有 review.md 模板）

---

跨模式对比

四种运行模式的适用场景一目了然：

模式	启动参数	有界面？	保存会话？	典型场景
交互	pi	✅ TUI	✅ 自动	日常编码、对话、探索
Print	pi -p	❌	可选	脚本集成、CI/CD、一次性问答
JSON	pi --mode json -p	❌	可选	程序调用、日志分析、管道处理
RPC	pi --mode rpc	❌	可选	SDK 编程、嵌入应用、长期进程

Print 模式默认不保存会话，加 --name 就可以保留。

---

编辑器快捷键

在交互模式的输入框里：

操作	快捷键
引用文件	输入 @ 弹出模糊搜索
路径补全	Tab
多行输入	Shift+Enter（Windows Terminal 上用 Ctrl+Enter）
复制回复	Ctrl+X（在 /tree 里复制选中的消息）
粘贴图片	Ctrl+V（Windows 上用 Alt+V）或拖入终端
外部编辑器	Ctrl+G——打开 externalEditor、$VISUAL、$EDITOR，或 Windows 的记事本
导向消息	Enter——在当前 turn 的工具调用结束后投递
跟进消息	Alt+Enter——在 agent 全部完成后投递（Windows Terminal 可能被全屏快捷键占用）
取消队列	Escape——取消已排队的消息
取回队列	Alt+Up——把已排队的消息取回编辑器

---

下一章转向 settings.json 的完整字段速查——每个字段的类型、默认值、配了之后会影响什么，全列出来。