跳转到内容

Pi 命令速查

先按“我想做什么”找到操作,再查下方的完整分类。以 pi 开头的命令在系统终端执行,以 / 开头的命令在 Pi 输入框执行。第一次使用请先完成10 分钟快速上手。

按日常场景速查

我想做什么直接操作
模型列表太长,只保留常用的几个/scoped-models → 取消全选 → 勾选 → Ctrl+S,详细步骤
快速找到并切换模型/model 或 Ctrl+L(List),输入关键词搜索,按 Enter
在常用模型之间轮换在主输入框按 Ctrl+P
下次启动仍使用这个模型在 /model 中选中模型,按 Ctrl+S
调整模型思考级别/thinking 或 Shift+Tab;在选择界面按 Ctrl+S 可保存为启动默认值
下次默认用 max/thinking 中选中 max 并按 Ctrl+S,或设置 defaultThinkingLevel;完整步骤与覆盖排查
看懂或配置底部 bar状态栏与 statusline:token、缓存、费用、上下文,以及主题和扩展
继续上次的工作终端执行 pi -c;挑选历史会话用 pi -r
已在 Pi 中,想换个会话/resume;开始新任务用 /new
运行方向错了,马上停止在生成回复或执行工具时按 Escape
看用量、费用和会话信息/session
上下文快满了/compact [需要重点保留的内容],何时压缩
工具输出占满屏幕在主输入框按 Ctrl+O(Output)折叠或展开
改了 Skill、Extension 或快捷键/reload
忘记快捷键/hotkeys
退出 Pi/quit

两个最容易混的短参数:-c 接着干(continue),-r 挑着续(resume)。其他短参数见短参数怎么记。

下面的模型操作与默认快捷键按 Pi 1.5.0(2026-11-05)核对。快捷键会随所在界面变化;主输入框的键位见 /hotkeys,选择器内的键位看底部提示。

模型列表太长,只保留常用模型

在 Pi 输入框执行:

/scoped-models
  1. 保持搜索框为空,按 Ctrl+X 取消全选。 如果已有搜索词,这个快捷键只取消当前搜索结果的勾选。
  2. 输入模型名或供应商名搜索,用方向键定位,按 Enter 勾选。清空搜索词后,再选择其他常用模型。
  3. 至少选中一个模型,再按 Ctrl+S 保存。 出现 Model selection saved to settings 后,按 Escape 返回。
  4. 再打开 /model,默认进入 scoped,只显示这些常用模型;在主输入框按 Ctrl+P,也只在这个范围内循环。

需要临时查看其他模型时,在 /model 内按 Tab,切换到 all。想长期增减常用模型,再打开 /scoped-models 修改并保存。

从零勾选与下次自动恢复

Pi 1.5.0 首次进入时默认全选,没有“首次默认空选”的设置。Ctrl+X 像“叉掉”,可以从零开始勾选;Ctrl+S 像 Save,会把范围保存到用户配置的 enabledModels,以后启动可复用。只勾选而不保存,修改仅对当前会话生效。

至少保留一个当前可用模型:空范围会回退到全部模型。Pi 仍会读取完整目录供你挑选,常用范围控制的是 /model 的默认展示和快捷循环。

搜索、切换与保存默认模型

所在界面操作结果
主输入框/model 或 Ctrl+L打开模型选择器
/model输入模型名或供应商名缩小当前范围内的搜索结果
/modelEnter切换当前会话使用的模型
/modelCtrl+S切换模型,并保存为以后新会话的默认值
/model,已设置常用范围Tab在 scoped(常用)和 all(全部)之间切换
/scoped-modelsCtrl+S保存常用模型范围
主输入框Ctrl+P循环切换到下一个模型
主输入框/thinking选择当前模型支持的思考级别
/thinkingEnter / Ctrl+S应用级别 / 应用并保存启动默认值

在 /model 和 /thinking 里,记法相同:Enter 只切这次,Ctrl+S 才存以后。

固定默认模型后,下一次启动通常就不需要再选;恢复历史会话时,Pi 会恢复该会话记录的模型。以上操作见 Pi 模型说明、快捷键参考与 Pi 1.5.0 模型选择器。

列表中的模型不保证当前账号都能调用;目录来源与权限的区别见认证与模型。

短参数怎么记

命令行短参数大多来自英文单词。先记单词,再记字母:

参数联想作用
-ccontinue继续当前目录最近一次会话,不弹列表
-rresume:先 review 一眼列表,再挑打开会话选择器,挑一个再恢复
-pprint输出最终回复后退出,适合脚本
-nname设置会话显示名称
-nano approve本次运行忽略项目本地资源
-aapprove本次运行信任项目本地资源
-llocal写入项目级配置或设置,而不是全局

一句话:接着干用 -c,挑着续用 -r;起名用 -n,本次忽略项目资源用 -na。

-c 只在当前目录里找最近会话;换过目录就用 -r,在选择器里按 Tab 把其他目录的会话也列出来。-n 和 -na 只差一个字母,含义完全不同:前者是命名,后者是 --no-approve(本次忽略项目本地资源)。

命令行结构

pi [options] [@files...] [messages...]

启动模式

命令用途
pi启动交互式终端界面
pi "任务"带首条消息启动交互会话
pi -p "任务"输出最终回复后退出
pi --mode json "任务"以 JSON Lines 输出所有事件
pi --mode rpc通过 stdin/stdout JSONL 供程序控制
pi --no-session临时会话,不写入会话文件

模型与认证

命令用途
/login登录订阅供应商或保存 API Key
/logout清除选定供应商的凭据
pi auth print-api-key --model <model> [--provider <provider>]输出指定模型使用的 API Key
pi auth print-bearer-token --model <model> [--provider <provider>]输出指定模型使用的 Bearer Token
/model搜索并切换模型,Ctrl+S 保存默认值
/scoped-models勾选常用模型,精简默认列表和快捷循环范围
/thinking选择思考级别,Ctrl+S 保存启动默认值
/llama管理 llama.cpp 路由器中的模型
pi --list-models [关键词]列出或搜索已配置供应商的模型目录
pi --provider <名称> --model <模型>启动时限定供应商并选择模型;--provider 不能单独使用
pi --model <模型>启动时指定模型或匹配模式
pi --thinking <级别>设置思考级别

--thinking 支持 off、minimal、low、medium、high、xhigh 和 max。实际可用级别取决于模型;pi --thinking max 只指定本次启动,不保存默认值。需要下次也用 max,按默认 max 教程操作;输入框边框颜色与虚拟模型的区别见模型、思考与主题。

pi auth print-* 会把真实凭据写到标准输出。只把它用于受控的进程管道,不要粘贴到聊天、日志或 CI 输出中;不确定时继续使用密钥管理系统注入环境变量。

如何在订阅、本机 API Key 和 CI 之间选择,见认证与模型。

会话

命令用途
pi -c继续当前目录最近一次会话
pi -r浏览并选择历史会话
pi --name "名称"启动时设置会话显示名称
pi --session <路径或 ID>打开指定会话
pi --fork <路径或 ID>从指定会话创建新的会话文件
/session查看当前会话文件、ID、用量和成本
/resume在交互界面选择历史会话
/new开始新会话
/name <名称>设置当前会话的显示名称
/tree跳到会话树中的任意节点
/fork从早期用户消息创建新会话
/clone把当前活动分支复制为新会话
/compact [说明]总结旧上下文,释放上下文窗口

会话默认保存在 ~/.pi/agent/sessions/,并按工作目录组织。

需要理解分支树和 steering / follow-up 队列,见日常使用与会话。

文件与输入

操作用途
在编辑器中输入 @模糊搜索项目文件
pi @README.md "概览"启动时引用单个文件
pi @a.ts @a.test.ts "审查"同时引用多个文件
Shift+Enter输入多行消息;Windows Terminal 通常使用 Ctrl+Enter
Ctrl+V粘贴文本或图片;Windows 通常使用 Alt+V
Ctrl+G在外部编辑器中编辑消息

Shell

输入行为
!command执行命令,并把输出加入模型上下文
!!command执行命令,但不把输出加入模型上下文

两者都以启动 Pi 的用户权限执行。记法:一个 ! 说给模型听,两个 !! 只给自己看。 区别只在输出是否进入模型上下文。

常用斜杠命令

命令用途
/settings修改主题、消息投递和传输等设置
/reload重载快捷键、上下文、扩展、技能、模板和主题
/trust保存项目信任决策
/copy复制最后一条助手消息
/export [文件]导出会话为 HTML 或 JSONL
/import <文件>导入并恢复 JSONL 会话
/share根据设置上传到 Radius 或 GitHub Gist 并生成链接
/hotkeys显示快捷键
/changelog查看版本变更
/quit退出 Pi

/share 会产生外部网络与云端状态变化。默认 auto 在已认证 Radius 时使用 Radius,否则创建 GitHub secret Gist;也可通过 sessionShareDestination 指定 gist 或 radius。Radius 的可见范围取决于组织权限;secret Gist 不出现在公开列表,但知道链接的人仍可访问。分享前检查会话内容。

工具范围

Pi 的内置工具包括:

  • read
  • write
  • edit
  • bash
  • grep
  • find
  • ls

默认主要工具是 read、write、edit 和 bash。可以在启动时限制:

终端窗口
pi --no-mcp --tools read,grep,find,ls
pi --exclude-tools bash,write,edit
pi --no-tools
pi --tools +codemode

注意:--tools read,grep,find,ls 本身不会排除 MCP 工具。上例用 --no-mcp 关闭内置 MCP,但不影响替代它的第三方扩展。--no-tools 禁用所有模型工具,--no-extensions 还能禁止自动发现的扩展,但显式 -e 仍会加载。工具 allowlist 不是操作系统级沙箱;详见 MCP 工具范围和权限与安全边界。

项目信任

参数行为
--approve, -a本次运行信任项目本地资源
--no-approve, -na本次运行忽略项目本地资源
/trust保存以后使用的信任决策

注意:-n 是 --name(命名会话),不是 --no-approve;要让本次忽略项目资源,要写 -na。非交互模式不会显示信任提示。没有已保存决策时,默认 ask 会让非交互运行跳过受保护的项目资源。

项目信任不限制文件和 shell 权限,完整解释见权限与安全边界。

MCP 与 Codemode

命令用途
pi mcp add <name> -- <command> [args...]配置本地 stdio 服务器;加 -l 写入项目配置
pi mcp add <name> --url <url>配置远程 streamable HTTP 服务器
pi mcp list连接并检查已启用的服务器
pi mcp login <name> / pi mcp logout <name>管理 MCP OAuth 登录
pi mcp remove <name>移除服务器配置,不自动删除 OAuth 凭据
/mcp在会话中查看服务器、登录和调整工具暴露
pi --no-mcp本次禁用内置 MCP,不禁用第三方替代扩展
pi --tools +codemode在默认工具之外启用 Codemode

pi mcp list 会启动本地服务器或访问远程服务。连接前先审查程序、权限与凭据。教程见 MCP 和 Codemode。

Pi 包

命令用途
pi install <来源> [-l]安装 Pi 包;-l 写入项目设置
pi remove <来源> [-l]移除 Pi 包
pi list列出已安装包
pi config启用或停用包资源
pi update / pi update --self更新 Pi;1.5 可配置自定义自更新命令
pi update --extensions更新已安装的 Pi Packages
pi update --models刷新模型目录
pi update --all更新 Pi 与已安装的 Pi Packages

安装第三方包会引入与当前用户同权限运行的代码。安装前先审查来源。1.5 的扩展包更新日志与自更新配置见升级指南。

还不确定应该使用 AGENTS.md、Skill、Extension 还是 Package?查看配置与扩展。

选择哪种模式

目标推荐模式
和 Pi 一起探索、修改项目交互模式
CI 中生成一段文本-p,并显式配置项目信任
记录完整结构化事件--mode json
从 IDE 或自定义 UI 控制 Pi--mode rpc
只做一次、不保留历史--no-session

需要协议约束、Node 子进程和 SDK 示例时,继续读自动化与程序集成。

完整 CLI 参考以 Using Pi 为准。