# 第 8 章：CLI 全参数速查
> 好手册不求读完，只求需要的那一秒恰好翻到。
## 设计思想
Pi 的命令行接口遵循"正交组合"：模式、模型、会话、工具、资源五类选项可以自由拼装，`--no-*` 系列与显式加载结合能构造出精确受控的运行环境。本章是全量速查，供按需检索。
## 原理与用法
### 总形式
```bash
pi [options] [--] [@files...] [messages...]
```
### 包管理命令
```bash
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` | 帮助 / 版本 |
### 文件参数
`@` 前缀把文件内容并入消息：
```bash
pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"
```
### 常用示例
```bash
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`。