好手册不求读完，只求需要的那一秒恰好翻到。
设计思想
Pi 的命令行接口遵循"正交组合"：模式、模型、会话、工具、资源五类选项可以自由拼装，--no-* 系列与显式加载结合能构造出精确受控的运行环境。本章是全量速查，供按需检索。
原理与用法
总形式
pi [options] [--] [@files...] [messages...]
包管理命令
pi install <source> [-l] # 安装包；-l 装到项目本地（.pi/npm/、.pi/git/）
pi remove <source> [-l] # 卸载（uninstall 为别名）
pi update # 只更新 pi 自身
pi update --all # 更新 pi + 所有包
pi update --extensions # 只更新包
pi update --models # 只刷新模型目录
pi update --self --force # 强制重装 pi
pi update npm:@foo/pi-tools # 更新指定包
pi list # 列出已安装的包
pi config # 启用/禁用包内资源
pi config 与包命令支持 --approve/--no-approve 处理项目信任；pi update 从不弹询问。
模式
| 参数 | 说明 |
|---|---|
| （默认） | 交互模式 |
-p, --print |
输出回复后退出；可管道合并 stdin：cat README.md | pi -p "Summarize this text" |
--mode json |
全部事件以 JSON 行输出（docs/json.md） |
--mode rpc |
RPC 模式，供进程集成（docs/rpc.md） |
--export <in> [out] |
导出会话为 HTML |
模型选项
| 参数 | 说明 |
|---|---|
--provider <name> |
提供商（anthropic、openai、google 等） |
--model <pattern> |
模型 pattern 或 ID；支持 provider/id 前缀和 :thinking 后缀（如 sonnet:high） |
--api-key <key> |
API key（优先于环境变量） |
--thinking <level> |
off / minimal / low / medium / high / xhigh / max |
--models <patterns> |
逗号分隔，限定 Ctrl+P 循环范围 |
--list-models [search] |
列出可用模型（可过滤） |
会话选项
| 参数 | 说明 |
|---|---|
-c, --continue |
继续最近会话 |
-r, --resume |
浏览选择历史会话 |
--session <path|id> |
指定会话文件或部分 UUID |
--fork <path|id> |
从既有会话分叉新会话 |
--session-dir <dir> |
自定义会话存储目录 |
--no-session |
一次性模式（不保存） |
--name <name>, -n |
启动时命名会话 |
工具选项
| 参数 | 说明 |
|---|---|
--tools <list>, -t |
工具白名单（内置+扩展+自定义通用） |
--exclude-tools <list>, -xt |
排除指定工具，其余保留 |
--no-builtin-tools, -nbt |
禁用内置工具，保留扩展/自定义工具 |
--no-tools, -nt |
禁用全部工具 |
内置工具：read、bash、powershell（Windows）、edit、write、grep、find、ls。
资源选项
| 参数 | 说明 |
|---|---|
-e, --extension <source> |
从路径/npm/git 加载扩展（可重复） |
--no-extensions |
停用扩展发现 |
--skill <path> |
加载 skill（可重复）；--no-skills 停用 |
--prompt-template <path> |
加载提示模板；--no-prompt-templates 停用 |
--theme <path> |
加载主题；--no-themes 停用 |
--no-context-files, -nc |
停用 AGENTS.md/CLAUDE.md 发现 |
组合技：--no-* + 显式 flag 可忽略 settings.json、精确控制加载内容，如 --no-extensions -e ./my-ext.ts。
其他选项
| 参数 | 说明 |
|---|---|
--system-prompt <text> |
替换默认系统提示（上下文文件与 skills 仍会追加） |
--append-system-prompt <text> |
追加系统提示 |
--tui-mode <mode> |
regular（默认）/ 实验 fullscreen |
--use-theme <name[/name]> |
单次运行主题，不改设置；light/dark 跟随终端外观 |
--verbose |
强制详细启动输出 |
-a / -na |
本次运行信任 / 忽略项目本地文件 |
-- |
停止解析选项，其后内容视为提示词或 @file |
-h, -v |
帮助 / 版本 |
文件参数
@ 前缀把文件内容并入消息：
pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"
常用示例
pi "List all .ts files in src/" # 交互 + 初始提示
pi -p -- "- Summarize these points" # 提示词以 - 开头时用 --
pi --name "release audit" -p "Audit this repository" # 命名的一次性会话
pi --model openai/gpt-4o "Help me refactor" # provider 前缀
pi --models "claude-*,gpt-4o" # 限定循环列表
pi --tools read,grep,find,ls -p "Review the code" # 只读模式
pi --exclude-tools ask_question # 排除单个工具
pi --thinking high "Solve this complex problem" # 高思考级别
环境变量
| 变量 | 说明 |
|---|---|
AI_AGENT |
CLI/RPC 入口设为 pi，供外部工具归因子进程 |
PI_CODING_AGENT |
设为 true，供子进程检测自己运行在 pi 内 |
PI_CODING_AGENT_DIR |
覆盖配置目录（默认 ~/.pi/agent） |
PI_CODING_AGENT_SESSION_DIR |
覆盖会话目录（被 --session-dir 覆盖） |
PI_PACKAGE_DIR |
覆盖包目录（Nix/Guix 场景有用） |
PI_OFFLINE |
禁用启动期全部网络操作 |
PI_SKIP_VERSION_CHECK |
跳过版本更新检查 |
PI_TELEMETRY |
覆盖遥测与归因头（1/0） |
PI_CACHE_RETENTION |
long 启用扩展缓存（Anthropic 1h / OpenAI 24h） |
VISUAL, EDITOR |
Ctrl+G 外部编辑器回退顺序 |
bash/powershell 工具执行命令时还会注入会话元数据（每条命令启动时解析）：
PI_SESSION_ID、PI_SESSION_FILE（临时会话时未设）、PI_PROVIDER、PI_MODEL、PI_REASONING_LEVEL。