#命令行

本页面是 Pi 官方文档 的中文翻译。仅供学习参考。

本页记录 Pi 内置的命令行命令和选项。运行 pi --help，或给某个命令加上 --help，可以查看你已安装版本的确切接口。顶层帮助还会包含已加载扩展注册的选项。

pi [options] [--] [@files...] [messages...]
pi install <source> [options]
pi remove <source> [options]
pi uninstall <source> [options]
pi update [target] [options]
pi list
pi config [options]
pi auth login <provider> [--api-key] [--no-browser]
pi auth logout <provider>
pi auth <check|print-api-key|print-bearer-token> [options]
pi mcp <add|remove|list|login|logout> [options]

#调用与输出

pi
pi --print "Summarize this repository"
git diff | pi --print "Review this change"
pi --mode json "Inspect this repository" > events.jsonl

当 stdin 和 stdout 都是终端时，Pi 会打开终端 UI，除非 --print、--mode json 或 --mode rpc 选择了其他接口。当任一数据流被重定向且未选择 JSON 或 RPC 模式时，Pi 使用 print 模式。交互、print、JSON、RPC 和 SDK 集成之间的选择见 CLI 集成。

Pi 从当前工作目录解析 @path。工作目录还控制项目配置、资源发现和会话分组。

--print 控制 Pi 是否运行一次后退出。--mode 选择输出接口。当 stdin 和 stdout 都是终端时，--mode text 不强制一次性执行；要这种行为请使用 --print。

RPC 模式拒绝 @file 参数。JSON 和 RPC 模式把 stdout 保留给协议记录。见 JSON 事件流和 RPC 协议。

#模型

pi --model sonnet:high

模型选择见选择模型，凭证见 Providers。

• --provider <name>
  把 --model 的查找限制在一个 Provider 内。它需要 --model。
• --model <pattern>
  通过精确 ID 或模糊的 ID/名称匹配选择。它接受 provider/id 和可选的 :<thinking> 后缀。如果有多个 Provider 匹配，Pi 优先选择有凭证的那个，否则会要求指定 --provider。
• --api-key <key>
  使用非持久的 API Key 覆盖。它需要通过 --model 或 --models 选择一个模型。它不会在提供同一模型的多个 Provider 之间做选择。
• --thinking <level>
  设置 off、minimal、low、medium、high、xhigh 或 max。它覆盖 --model 的后缀，并会被限制到模型的能力范围内。
• --models <patterns>
  为启动和循环设置逗号分隔的范围。它接受精确 ID、模糊匹配、大小写不敏感的 glob 和可选的 :<thinking> 后缀。由多个 Provider 提供的模型会为每个 Provider 各添加一个，并给出警告。
• --list-models [search]
  列出可用模型，可选地按模糊搜索过滤，然后退出。

#会话

pi --continue

恢复、fork、命名和存储会话见会话与上下文。

• -c、--continue
  继续当前目录最近的会话。
• -r、--resume
  打开会话选择器，并在所选会话的工作目录中恢复它。按 Tab 可以包含其他目录的会话。
• --session <path|id>
  按文件路径或完整/部分 ID 打开会话，并在其工作目录中恢复。如果该 ID 只匹配其他目录下存储的会话，Pi 会提议把它 fork 到当前目录，而不是直接打开。
• --session-id <id>
  打开当前目录中已有的该 ID 会话，否则创建它。ID 接受字母、数字、.、_ 和 -。
• --fork <path|id>
  按文件路径或完整/部分 ID 选择会话，并 fork 成当前目录中的新会话。
• --session-dir <dir>
  覆盖存储和查找位置。它的优先级高于 PI_CODING_AGENT_SESSION_DIR 和 sessionDir 设置。
• --no-session
  使用不持久化的内存会话。
• -n、--name <name>
  设置会话显示名。

约束：

• 会话 ID 必须由字母或数字开头和结尾。
• --fork 不能与 --session、--continue、--resume 或 --no-session 组合。
• --session-id 不能与 --session、--continue 或 --resume 组合。与 --fork 组合可以用它选择新的 ID。

#工具

pi --tools read,grep,find,ls --print "Review this project"

配置默认工具选择见设置。

• -t、--tools <list>
  用逗号分隔的内置、扩展或自定义工具允许列表替换默认选择。条目是工具名或模式，其中 * 匹配任意字符。除非某个条目以 mcp__ 开头，否则保留 MCP 工具（见 MCP 工具）。只含 +name 和 -name 的列表不是允许列表；它会改动默认选择。
• -xt、--exclude-tools <list>
  在所有其他选择选项之后禁用逗号分隔的工具名或模式，包括 MCP 工具。
• -nbt、--no-builtin-tools
  禁用默认内置工具，同时保留扩展和自定义工具。
• -nt、--no-tools
  启动时禁用所有内置、扩展、自定义和 MCP 工具。

默认启用的工具是 read、bash、edit 和 write，除非 defaultTools 改变了它们。用普通名称时，--tools 会替换整个选择，所以要写出你想要的每个工具。与 defaultTools 一样，它也接受只含 +name 和 -name 的列表，这会从默认选择中添加或移除工具：pi --tools +codemode,-write 保留其他默认工具、启用 codemode 并禁用 write。这些条目只接受精确的工具名，不接受 * 模式；要按模式禁用工具，用 --exclude-tools。普通名称和 +name/-name 条目不能混用。/reload 会启用新加入 defaultTools 的工具，但用 -name 移除的工具会保持移除。

--tools 选择声明给模型的工具。它不移除 MCP 工具，后者的可及范围由它们的 exposure 决定：pi --tools read,codemode 会保留所有可从 codemode 脚本调用的 MCP 工具。没有任何条目点名或匹配的 MCP 工具永远不会被直接声明，无论它的 exposure 是什么；只有 tool_search（如果列出）能加载它。一旦某个条目以 mcp__ 开头，--tools 也会过滤 MCP 工具，因此下面只保留 radius 服务器的工具：

pi --tools read,bash,codemode,'mcp__radius__*'

MCP 资源工具（list_mcp_resources、list_mcp_resource_templates、read_mcp_resource）算作 MCP 工具。要移除 MCP 工具，用 --exclude-tools 'mcp__*' 或 --no-mcp。

内置扩展再提供两个工具。它们默认关闭；MCP 扩展在 MCP 服务器需要它们时会打开（见 MCP）。要自己启用，在 --tools 或 defaultTools 中写出它们。

#启用 codemode

要为每个会话打开 codemode，把它加到 ~/.pi/agent/settings.json 或项目 .pi/settings.json 的默认工具中：

{
  "defaultTools": ["+codemode"]
}

这会保留 read、bash、edit 和 write，并加上 codemode。单次调用可用 --tools 加上它：

pi --tools +codemode

没有 MCP 时，codemode 仍然有用：脚本可以并行运行多个 tool call、在输出到达模型前过滤大量输出，通过 models.classify() 调用 TypeSafe 的 Jev 等分类器模型（见分类器模型），并通过 models.generateImages() 生成图片（见图片模型）。

#codemode 如何工作

脚本在 QuickJS 沙箱中运行，通过 tools.<name>(args) 到达其他工具。Codemode 描述脚本 API、工具如何列出和查找、store() 和 models 全局变量，以及限制。

#工具搜索

tool_search 默认关闭；用 "defaultTools": ["+tool_search"] 或 --tools 启用。它用与 searchTools() 相同的排序，覆盖尚未声明的工具，并把匹配项声明给下一次模型调用。已加载的工具像其他工具变更一样记入会话，因此在该分支上保持声明。

#资源

pi --extension ./review.ts

约定目录和项目信任见配置，已配置的路径见设置，包来源见 Pi 包。

• -e、--extension <path>
  加载一个扩展文件或目录，或内置扩展（例如 builtin:mcp），可重复。
• -ne、--no-extensions
  禁用已发现、已配置和内置的扩展。显式的 -e 路径仍会加载，所以 pi -ne -e builtin:mcp 只保留内置 MCP 支持。
• --no-mcp
  为本次运行禁用内置 MCP 支持：不连接任何服务器，没有 MCP 工具，也没有 /mcp。它不影响替代内置 MCP 支持的扩展。
• --skill <path>
  加载一个 Skill 文件或目录，可重复。
• -ns、--no-skills
  禁用已发现和已配置的 Skill。显式的 --skill 路径仍会加载。
• --prompt-template <path>
  加载一个 Prompt 模板文件或目录，可重复。
• -np、--no-prompt-templates
  禁用已发现和已配置的模板。显式的 --prompt-template 路径仍会加载。
• --theme <path>
  加载一个主题文件或目录，可重复。
• --use-theme <name[/name]>
  为本次运行选择初始交互主题。
• --no-themes
  禁用已发现和已配置的主题。显式的 --theme 路径仍会加载。
• -nc、--no-context-files
  禁用 AGENTS.md 和 CLAUDE.md 的发现。

资源路径只作用于当前进程。相对路径从当前工作目录解析。

#Prompt 与进程

pi --append-system-prompt ./instructions.md

已保存的配置见配置，项目信任见安全，进程控制见环境变量。

• --system-prompt <text|path>
  用文本或已有文件的内容替换默认系统提示。
• --append-system-prompt <text|path>
  把文本或已有文件追加到系统提示，可重复。
• --tui-mode <mode>
  使用 fullscreen（默认）或 regular 终端模式。
• --verbose
  显示详细的交互式启动信息，覆盖 quietStartup。
• -a、--approve
  为本进程信任项目本地配置和资源。
• -na、--no-approve
  为本进程忽略受信任门控的项目本地配置和资源。
• --offline
  禁用自动网络活动，包括模型目录刷新。等价于 PI_OFFLINE=1。
• -h、--help
  显示帮助（包括已加载扩展注册的标志），然后退出。
• -v、--version
  显示 Pi 版本，然后退出。

扩展可以注册额外的长格式选项。未知的短选项会被拒绝。

#包命令

pi install npm:@scope/package

来源格式、过滤、安装和项目作用域见 Pi 包。

#常见任务

给 install、remove、uninstall 或 config 加上 --local 或 -l，可以使用项目设置而不是全局设置。

#更新 Pi 或包

不带目标运行 pi update 会更新 Pi 自身。

当所选的更新包含 Pi 时，加上 --force 可以重新安装 Pi。

pi update 无法更新由其他包管理器提供的 Pi（例如 Nix）。请用该包管理器更新 Pi，例如 nix profile upgrade pi。包和模型目录更新仍然可用。

#自定义更新命令

如果 Pi 由包装脚本或其他包管理器提供，设置 PI_SELF_UPDATE_COMMAND，让 pi update 运行它的更新命令：

export PI_SELF_UPDATE_COMMAND="mise use -g npm:{packageName}@{version}"

只有 pi.dev 有更新的发布时，pi update 才会运行它，并把 {packageName}、{version} 和 {installSpec}（{packageName}@{version}）替换为该发布的值。值按空格拆分。参数含空格时，改用 ~/.pi/agent/settings.json 里的 selfUpdateCommand 设置，它是 argv 数组，例如 ["nix", "profile", "upgrade", "pi"]。

#别名和命令选项

• pi uninstall <source> 是 pi remove <source> 的别名。
• pi update --self、pi update self 和 pi update pi 是 pi update 的别名。
• pi update --extension <source> 是 pi update <source> 的别名。
• -a、--approve 为一个命令信任项目本地文件。-na、--no-approve 忽略受信任门控的项目本地文件。
• 给命令追加 -h 或 --help 可以查看它的确切用法和选项约束。

#凭证命令

pi auth login <provider> 在终端登录某个 Provider 后退出，不启动会话。它用账号登录并打开浏览器，和 /login <provider> 一样。没有账号登录的 Provider 会要求 API Key。登录 Radius 时，如果还没有全局服务器使用该登录，还会把 Radius MCP 服务器加到 ~/.pi/agent/mcp.json。它需要交互式终端。

pi auth logout <provider> 移除 pi auth login 或 /login 保存的凭证，和 /logout 一样。环境变量和 models.json 配置不变。没有已保存凭证时以状态 0 退出，所以可以重复执行。

pi auth login radius
pi auth logout radius
pi auth check --provider openai --json

其他认证命令需要 --provider <provider> 或 --model <model>。受支持的方式见 Providers。

输出凭证的命令会把 secret 写到 stdout。

#MCP 命令

这些命令在会话之外工作，因此 agent 可以通过 bash 运行它们。见 MCP 服务器。

add 和 remove 修改 ~/.pi/agent/mcp.json，加上 --local（-l）则修改当前目录的 .pi/mcp.json。add 还接受 --exposure <mode>（见 控制工具暴露）和 --description <text>，并且不会连接；运行 pi mcp list 检查服务器。

项目 .pi/mcp.json 文件只对已经受信任的项目读取。

法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。