📊 页面导航

    适用角色与上手难度

    角色推荐度上手难度
    🛠️ 开发★★★★★★★☆☆☆
    🧪 测试★★★★☆★★☆☆☆
    📦 产品★★★☆☆★★★☆☆

    🎯 学习产出： 掌握 Pi 的所有 CLI 子命令、启动参数和管道操作，能独立用命令行控制 Pi

    🚀 AI 能力提升： 自动化工作流

    CLI 常用命令

    预计阅读时间: 7 分钟

    Pi 的命令行界面，用于启动会话、管道内容、恢复对话、管理包和模型。

    基本用法

    pi [options] [--] [@files...] [messages...]
    命令说明示例
    pi启动交互式会话pi
    pi "query"带初始提示启动交互式会话pi "explain this project"
    pi -p "query"非交互模式，输出回答后退出pi -p "explain this function"
    cat file | pi -p "query"处理管道输入内容cat logs.txt | pi -p "explain"
    pi -c继续当前目录下最近的会话pi -c
    pi -r浏览并选择过去的会话pi -r
    pi --fork <id> "query"从某个会话分叉出新会话pi --fork abc123 "Finish this PR"
    pi --export <in> [out]将会话导出为 HTMLpi --export session.jsonl report.html
    pi --list-models [search]列出可用模型（支持模糊搜索）pi --list-models sonnet

    会话选项

    选项说明示例
    -c, --continue继续最近的会话pi -c "check for type errors"
    -r, --resume浏览并选择要恢复的会话pi -r
    --session <path|id>使用指定会话文件或部分 UUIDpi --session abc123
    --fork <path|id>将指定会话复制到新会话pi --fork abc123
    --session-dir <dir>自定义会话存储目录pi --session-dir ~/pi-sessions
    --no-session临时模式，不保存会话pi --no-session
    -n, --name <name>设置会话显示名称pi -n "auth-refactor"
    --export <in> [out]把会话导出为 HTML 后退出pi --export s.jsonl s.html

    模型选项

    选项说明示例
    --provider <name>指定 provider（anthropic、openai、google 等）pi --provider anthropic
    --model <pattern>模型模式或 ID，支持 provider/id 和 :<thinking> 后缀pi --model anthropic/claude-sonnet-4
    --api-key <key>API key（覆盖环境变量）pi --api-key sk-...
    --thinking <level>思考级别：off/minimal/low/medium/high/xhigh/maxpi --thinking high
    --models <patterns>逗号分隔的模式，用于 Ctrl+P 循环切换，支持通配符pi --models "anthropic/*,*sonnet*"
    --list-models [s]列出可用模型pi --list-models

    工具选项

    选项说明示例
    -t, --tools <list>允许列表：只启用指定的工具pi -t read,bash
    -xt, --exclude-tools <list>禁用列表：关闭指定的工具pi -xt edit,write
    -nt, --no-tools默认禁用所有工具（内置和扩展）pi -nt
    -nbt, --no-builtin-tools默认禁用内置工具，但保留扩展/自定义工具pi -nbt

    内置工具：read、bash、edit、write、grep、find、ls（Windows 还有 powershell）。

    资源选项

    选项说明示例
    -e, --extension <src>从路径、npm 或 git 加载扩展（可重复）pi -e ./my-ext.ts
    --no-extensions禁用扩展发现pi --no-extensions
    --skill <path>加载技能（可重复）pi --skill ./skills/foo
    --no-skills禁用技能发现pi --no-skills
    --prompt-template <path>加载提示词模板（可重复）pi --prompt-template ./p.md
    --theme <path>加载主题（可重复）pi --theme ./dark.json
    --use-theme <name>本次运行使用指定主题pi --use-theme dark
    -nc, --no-context-files禁用 AGENTS.md / CLAUDE.md 发现pi -nc
    精确控制

    把 --no-* 和显式参数组合，可以只加载你需要的资源、忽略 settings.json。例如 pi --no-extensions -e ./my-ext.ts。

    包管理命令

    pi install <source> [-l]     # 安装包（npm/git/ssh/https），-l 为项目本地安装
pi remove <source> [-l]      # 移除包
pi uninstall <source> [-l]   # remove 的别名
pi update [source|self|pi]   # 只更新 pi 或某个包
pi update --all              # 更新 pi 和所有包
pi update --extensions       # 只更新包
pi update --models           # 只刷新模型目录
pi update --self             # 只更新 pi
pi update --self --force     # 强制重装 pi
pi list                      # 列出已安装的包
pi config                    # 启用/禁用包资源（Tab 切换作用域）

    安装来源示例：

    pi install npm:@foo/pi-tools              # npm 包
pi install npm:@foo/pi-tools@1.2.3        # 固定版本
pi install git:github.com/user/repo       # git 仓库
pi install git:github.com/user/repo@v1    # 指定 tag/commit
pi install https://github.com/user/repo   # https 地址
pi install ssh://git@github.com/user/repo # ssh 地址

    认证命令

    pi auth print-api-key --provider openai      # 打印 provider 的 API key，供外部客户端使用
pi auth print-bearer-token --provider openai-codex  # 打印 OAuth bearer token（过期自动刷新）

    其他常用参数

    参数说明
    --system-prompt <text>替换默认提示词（上下文文件和技能仍会附加）
    --append-system-prompt <t>追加到系统提示词
    -a, --approve本次运行信任项目本地文件
    -na, --no-approve本次运行忽略项目本地文件
    --offline禁用启动时网络操作（等同于 PI_OFFLINE=1）
    --verbose强制显示启动详情
    --结束选项解析，剩余参数都作为提示词或 @file 输入
    -h, --help显示帮助
    -v, --version显示版本号
    Tip

    扩展可以注册额外的命令行参数（例如 plan-mode 扩展会注册 --plan）。安装扩展后用 pi --help 查看新增参数。

    示例

    # 交互式带初始提示
pi "List all .ts files in src/"

# 把文件作为初始消息
pi @prompt.md @image.png "What color is the sky?"

# 非交互式：处理并退出
pi -p "Summarize CHANGELOG.md"

# 管道输入
cat errors.log | pi -p "Find the root cause"

# 恢复会话并继续
pi -c -p "Check for type errors"

# 用指定模型开启交互会话
pi --provider anthropic --model anthropic/claude-sonnet-4

# 导出会话为 HTML
pi --export session.jsonl report.html

    下一步