CLI 参考

Preview docs describe unreleased preview builds. Stable docs remain at /docs/.

Nagi 的 CLI 通过与集成和智能体相同的本地 socket API 与运行中的服务器通信。

大多数命令输出 JSON 响应。需要确定性自动化时,从脚本中使用它们。

启动与状态

nagi                         # 启动或连接默认会话
nagi --session work          # 启动或连接命名会话
nagi --remote workbox        # 通过 SSH 连接,使用本地按键绑定
nagi --remote workbox --remote-keybindings server
nagi --remote workbox --handoff
nagi --no-session            # 单进程逃生舱
nagi --default-config        # 打印默认配置
nagi update                  # 从配置的通道下载并安装
nagi update --handoff        # 对受支持的运行中服务器启用实时交接
nagi completion zsh          # 生成 zsh 补全脚本
nagi channel show            # 打印 stable 或 preview
nagi channel set preview     # 启用预览构建
nagi channel set stable      # 把 Linux/macOS 直接安装切回稳定版
nagi --version               # 打印版本

状态命令:

nagi status
nagi status server
nagi status client

API schema 命令:

nagi api schema
nagi api schema --json
nagi api schema --output nagi-api.schema.json

nagi api schema 会打印安装的二进制中包含的 socket 协议 schema 简短摘要。需要完整 JSON Schema 文档时使用 --json;要写入文件则使用 --output PATH。

Shell 补全

nagi completion zsh
nagi completions zsh
nagi completion bash
nagi completion fish
nagi completion powershell
nagi completion elvish

completion 会把脚本打印到 stdout。completions 是别名。临时 zsh 会话可以直接加载脚本:

source <(nagi completion zsh)

持久 zsh 设置中,把生成的 _nagi 函数写到 compinit 运行前已经在 fpath 上的位置:

mkdir -p ~/.zfunc
nagi completion zsh > ~/.zfunc/_nagi

然后确认 .zshrc 包含:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

服务器

nagi server
nagi server stop
nagi server reload-config
nagi server agent-manifests [--json]
nagi server update-agent-manifests [--json]
nagi server reload-agent-manifests

nagi server 显式运行无界面服务器,适合被监管或服务式的部署。reload-config 在不重启窗格的情况下应用可重载设置。agent-manifests 显示生效的智能体检测清单来源、缓存的远程版本和最近的远程更新结果。update-agent-manifests 立即拉取远程清单更新,重载到运行中的服务器,并打印更新后的清单状态;要原始状态响应就加 --json。reload-agent-manifests 在编辑本地覆盖后,把智能体检测清单重载到运行中的服务器。

通知

nagi notification show <title> [--body TEXT] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request]

notification show 使用配置的 [ui.toast] 投递方式。--position 只影响 Nagi 应用内的 toast。--sound 默认为 none;done 和 request 只在通知实际显示时播放已有的完成音和需要关注音。

会话

nagi session list [--json]
nagi session attach <name>
nagi session stop <name> [--json]
nagi session delete <name> [--json]

需要显式停止默认会话时,把会话名写成 default。

工作区

nagi workspace list
nagi workspace create [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
nagi workspace get <workspace_id>
nagi workspace focus <workspace_id>
nagi workspace rename <workspace_id> <label>
nagi workspace report-metadata <workspace_id> --source ID [--token NAME=VALUE] [--clear-token NAME] [--seq N] [--ttl-ms N]
nagi workspace close <workspace_id>

不抢占焦点地创建工作区:

nagi workspace create --cwd ~/project --label api --no-focus

Worktree

nagi worktree list [--workspace ID | --cwd PATH] [--json]
nagi worktree create [--workspace ID | --cwd PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--json]
nagi worktree open [--workspace ID | --cwd PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--json]
nagi worktree remove --workspace ID [--force] [--json]

worktree 是带有 Git 检出来源信息的普通 Nagi 工作区。worktree create 创建一个 Git worktree 检出,作为工作区打开,并与父仓库工作区分到一组。如果 --branch 指向已有的本地分支,Nagi 检出它;否则从 --base 或 HEAD 创建分支。没有 --path 时,Nagi 在 <worktrees.directory>/<repo>/<branch-slug> 下创建检出。

workspace close 只关闭 Nagi 状态。worktree remove 是显式的检出删除路径;它运行 git worktree remove,从不删除分支,并在 Git 拒绝脏检出时要求 --force。

仓库可以在 .nagi/project.toml 中声明有界的 setup、检查、服务、cleanup 和 精确的忽略文件复制。检测和验证不会执行仓库代码，所有执行都必须显式传入 --yes:

nagi project detect [PATH] [--json]
nagi project validate [PATH] [--json]
nagi project setup [PATH] --yes [--json]
nagi project check [PATH] [--id ID] --yes [--json]
nagi project cleanup [PATH] --yes [--json]
nagi project services start [PATH] --mission ID --run ID --yes [--json]
nagi project services status [PATH] --mission ID --run ID [--json]
nagi project services stop [PATH] --mission ID --run ID --yes [--json]
nagi project resources preview [--json]
nagi project resources apply --digest DIGEST --yes [--json]

服务获得无冲突的 loopback 端口，并必须通过声明的 HTTP 健康检查。同一 mission/run 的健康服务会在 Nagi 重启后被接管，而不会重复启动。cleanup 只应用与用户已审核 digest 完全一致的预览。worktree 只复制明确声明的普通文件；symlink、glob、疑似密钥名称、 超大文件和覆盖写入都会关闭失败。

任务

nagi mission list
nagi mission get <mission_id>
nagi mission proof <mission_id>
nagi mission close <mission_id>
nagi mission handoff <mission_id> --to <codex|claude-code|opencode|acp> --preview
nagi mission handoff <mission_id> --to <provider> --start --artifact-sha256 <sha256> --generated-at-millis <timestamp>

建议在驾驶舱中执行交接: 打开处于阻塞或审核状态的任务,按 h 检查绑定的工作区 快照,选择下一个提供商,然后确认写入范围。CLI 启动命令要求使用预览输出的精确摘要 和时间戳,因此自动化无法从过期上下文继续执行。

ACP 智能体是无需 shell 的本地 stdio 进程:

[providers.acp]
command = ["my-acp-agent", "--stdio"]

标签页

nagi tab list [--workspace <workspace_id>]
nagi tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
nagi tab get <tab_id>
nagi tab focus <tab_id>
nagi tab rename <tab_id> <label>
nagi tab close <tab_id>

窗格

nagi pane list [--workspace <workspace_id>]
nagi pane current [--pane ID|--current]
nagi pane get <pane_id>
nagi pane layout [--pane ID|--current]
nagi pane process-info [--pane ID|--current]
nagi pane neighbor --direction left|right|up|down [--pane ID|--current]
nagi pane edges [--pane ID|--current]
nagi pane focus --direction left|right|up|down [--pane ID|--current]
nagi pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current]
nagi pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off]
nagi pane rename <pane_id> <label>|--clear
nagi pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--focus] [--no-focus]
nagi pane swap --direction left|right|up|down [--pane ID|--current]
nagi pane swap --source-pane ID --target-pane ID
nagi pane move <pane_id> --tab <tab_id> --split right|down [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus]
nagi pane move <pane_id> --new-tab [--workspace ID] [--label TEXT] [--focus|--no-focus]
nagi pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--focus|--no-focus]
nagi pane close <pane_id>

读取输出:

nagi pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N]
nagi pane read <pane_id> --source visible --ansi
nagi pane read <pane_id> --source recent-unwrapped --lines 120

发送输入:

nagi pane send-text <pane_id> <text>
nagi pane send-keys <pane_id> <key> [key ...]
nagi pane run <pane_id> <command>

<key> 使用 Nagi 的组合键语法: a 这类普通可打印键,enter、tab、esc、backspace、left、right、up、down 这类特殊键,ctrl+h、control+j、alt+x、shift+tab 这类修饰组合键,f1 这类功能键,以及 minus、plus、backtick 这类命名标点。旧式的 C-c 和 c-c 作为 ctrl+c 的别名被接受。

pane run 把文本和回车作为一个原子操作提交。发送命令时优先用它,而不是 send-text 加 send-keys Enter。

从自定义钩子上报智能体状态:

nagi pane report-agent <pane_id> \
  --source ID \
  --agent LABEL \
  --state idle|working|blocked|unknown \
  [--message TEXT] \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path PATH]

当官方集成上报了原生会话引用时,pane get、pane list、agent get 和 agent list 会包含一个只读的 agent_session 对象。没有存储原生会话引用时,该字段被省略。

当 Nagi 能解析控制窗格的前台进程的 cwd 时,这些命令会包含 foreground_cwd。已有的 cwd 字段仍然是用于标签和 follow-cwd 行为的窗格/工作区 cwd。

上报仅用于展示的窗格元数据,而不接管语义状态:

nagi pane report-metadata <pane_id> \
  --source ID \
  [--agent LABEL] \
  [--applies-to-source ID] \
  [--title TEXT|--clear-title] \
  [--display-agent TEXT|--clear-display-agent] \
  [--state-label STATUS=TEXT] \
  [--clear-state-labels] \
  [--token NAME=VALUE] \
  [--clear-token NAME] \
  [--seq N] \
  [--ttl-ms N]

STATUS 是 idle、working、blocked、done 或 unknown 之一。--agent 和 --applies-to-source 只守卫 --title、--display-agent 和 --state-label,不守卫令牌补丁。上报方负责清除令牌或刷新 TTL。用 --display-agent 修改可见名称。

元数据文本在存储前会被规范化。Nagi 去掉首尾空白、移除控制字符,并把 --title、--display-agent、每个 --state-label 和令牌值截断到 80 个字符。规范化后为空的令牌值会清除该键。

--token 设置一个命名展示值,--clear-token 删除一个值。未提及的令牌保持不变。窗格令牌可在智能体侧边栏行中写成 $name;工作区令牌可用于空间行。TTL 分别应用于该次调用更新的每个令牌键。

--source 和 --applies-to-source 必须不超过 80 个字符,并且只能包含 ASCII 字母、数字、冒号、点、下划线和连字符。--ttl-ms 让元数据自动过期,取值必须在 1 到 86400000 毫秒之间。想让元数据一直保留到被替换、清除或窗格或工作区关闭时,省略它。--seq 让 Nagi 忽略来自同一 --source 的过期上报;过期上报会被 API 接受,但被窗格状态忽略。每个窗格或工作区在其生命周期内最多接受来自 32 个不同来源的带序号令牌上报,清除或过期不会释放这些来源名额。

智能体

nagi agent list
nagi agent get <target>
nagi agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
nagi agent send <target> <text>
nagi agent rename <target> <name>|--clear
nagi agent focus <target>
nagi agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
nagi agent attach <target> [--takeover]
nagi agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
nagi agent explain <target> [--json|--verbose]
nagi agent explain --file PATH --agent LABEL [--json|--verbose]

智能体目标可以是终端 ID、唯一的智能体名称、检测到或上报的智能体标签,以及旧式窗格 ID。名称和标签是智能体的身份。终端 ID 和旧式窗格 ID 是底层的逃生舱。

agent read 读取解析出的终端流。agent send 向该流写入字面文本。agent get、agent focus、agent wait 和 agent attach 要求解析出的终端具有智能体身份。agent rename 可以赋予这个身份。

agent explain 请求运行中的服务器对屏幕检测所用的同一份底部缓冲区检测快照进行分类,因此实时输出反映服务器生效的清单缓存。因为它使用 agent.explain socket 方法,升级 Nagi 后,请先重启或交接到更新后的服务器,再使用实时 explain。用 --file PATH --agent LABEL 可以改为在本地解释一份保存的样本。默认输出显示智能体、最终状态、清单来源和版本、匹配的规则及其区域证据,以及任何回退、跳过或警告原因。加 --verbose 可以看到可见证据标志、缓存的远程版本、本地覆盖的遮蔽情况、远程更新状态,以及带匹配器和区域证据的完整已评估规则列表。提交问题报告或写测试时加 --json。

普通终端、服务器、测试、shell 或底层终端控制,请使用 pane send-text、pane send-keys、pane run 和 terminal attach。想带回车提交命令时用 pane run。

直接终端附加

nagi terminal attach <terminal_id> [--takeover]
nagi terminal title set <title>
nagi terminal title clear

从直接附加中用 ctrl+b q 分离。用 ctrl+b ctrl+b 发送字面的 ctrl+b。 terminal title clear 恢复 Nagi 默认的外层终端窗口标题。

等待

等待窗格中的输出:

nagi wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]

等待窗格的智能体状态:

nagi wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]

普通命令和服务器用 wait output。编程智能体用 wait agent-status。

集成

nagi integration install pi
nagi integration install omp
nagi integration install claude
nagi integration install codex
nagi integration install copilot
nagi integration install devin
nagi integration install droid
nagi integration install kimi
nagi integration install opencode
nagi integration install kilo
nagi integration install hermes
nagi integration install mastracode
nagi integration install qodercli
nagi integration install cursor
nagi integration uninstall pi
nagi integration uninstall omp
nagi integration uninstall claude
nagi integration uninstall codex
nagi integration uninstall copilot
nagi integration uninstall devin
nagi integration uninstall droid
nagi integration uninstall kimi
nagi integration uninstall opencode
nagi integration uninstall kilo
nagi integration uninstall hermes
nagi integration uninstall mastracode
nagi integration uninstall qodercli
nagi integration uninstall cursor
nagi integration status [--outdated-only]

插件

插件命令用于安装和运行本地可执行的工作流插件。插件是清单加进程外命令;Nagi 负责宿主侧,插件负责自己的实现语言。

安装、列出和移除插件:

nagi plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
nagi plugin list [--plugin ID] [--json]
nagi plugin uninstall <plugin_id|owner/repo[/subdir...]>
nagi plugin enable <plugin_id>
nagi plugin disable <plugin_id>

plugin install 只接受 GitHub 简写,比如 owner/nagi-plugin/worktree-bootstrap。它使用 git,在交互式终端显示信任预览,运行受支持的清单构建命令,并把 GitHub 安装保存在 Nagi 管理的目录中。非交互式安装用 --yes。重新安装 GitHub 管理的插件会替换该托管检出。不允许覆盖安装到本地链接的插件之上。插件清单必须声明 min_nagi_version;当插件要求更新的 Nagi 二进制时,install 和 link 会失败。plugin list 默认是人类可读的;要原始 API 响应就传 --json。

本地开发:

nagi plugin link <path> [--disabled]
nagi plugin unlink <plugin_id>

plugin link 接受包含 nagi-plugin.toml 的插件目录,或直接指向清单的路径。从本地检出编写或测试插件时,它仍然是正确的命令。plugin unlink 注销插件、不动文件。plugin uninstall 注销插件,并同时删除 Nagi 管理的 GitHub 检出文件。对 GitHub 安装,uninstall 既接受插件 id,也接受与 install 相同的 owner/repo[/subdir...] 简写。动作、事件钩子、窗格和链接处理器在清单中声明;运行时动作注册不在 v1 范围内。

配置目录:

nagi plugin config-dir <plugin_id>

plugin config-dir 打印插件的配置目录,需要时会创建它 (旧版插件配置位置存在时会从那里初始化)。在安装文档和 shell 脚本中用它给用户指出一个稳定路径,用于存放 .env 等用户可编辑配置,与托管的插件检出分开。

动作:

nagi plugin action list [--plugin ID]
nagi plugin action invoke <action_id> [--plugin ID]

plugin action invoke 为一个已安装、已启用、平台兼容的插件动作启动清单命令,并在 JSON 响应中打印已启动命令的日志记录。当多个插件使用相同的动作 id 时,使用限定的动作 id (plugin.id.action)。本地动作 id 不能包含点,所以即使插件 id 包含点,限定 id 也不会有歧义。

日志:

nagi plugin log list [--plugin ID] [--limit N]

托管终端窗格:

nagi plugin pane open --plugin ID --entrypoint ID [--placement overlay|popup|split|tab|zoomed] [--width SIZE] [--height SIZE] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
nagi plugin pane focus <pane_id>
nagi plugin pane close <pane_id>

plugin pane open 要求插件已链接、已启用并与当前平台兼容。它把清单声明的 [[panes]] 命令作为 Nagi 管理的终端窗格启动。清单的默认值是 overlay,在活动窗格上方打开一个临时的缩放覆盖层。它也可以作为分割、新标签页、缩放窗格,或不改变标签页布局的会话级模态 popup 打开。--width 和 --height 以终端单元格数或 80% 这样的百分比设置弹窗外层尺寸;省略时默认为终端大小的一半,过小的值会限制为弹窗最小尺寸。弹窗不是 Nagi 窗格,不会收到 NAGI_PANE_ID,也不参与 pane 或智能体 API。非终端的原生插件窗格是之后的能力面。

--env KEY=VALUE 可以在启动进程的命令上重复使用,只作用于新启动的进程。当与调用方提供的环境变量冲突时,NAGI_SOCKET_PATH、NAGI_BIN_PATH、NAGI_ENV、NAGI_WORKSPACE_ID、NAGI_TAB_ID、NAGI_PANE_ID、NAGI_PLUGIN_ID、NAGI_PLUGIN_ROOT、NAGI_PLUGIN_CONFIG_DIR、NAGI_PLUGIN_STATE_DIR、NAGI_PLUGIN_ENTRYPOINT_ID 和 NAGI_PLUGIN_CONTEXT_JSON 等 Nagi 管理的变量保持权威。

读取来源

来源	含义
visible	当前渲染的屏幕。最适合 UI 反馈循环。
recent	带终端折行的最近回滚内容。
recent-unwrapped	不带软折行的最近回滚内容。最适合日志。
detection	智能体屏幕检测使用的底部缓冲区快照。

环境变量

变量	用途
NAGI_CONFIG_PATH	覆盖配置文件路径。
NAGI_SESSION	为 CLI 命令选择命名会话。
NAGI_SOCKET_PATH	底层 socket 路径覆盖。
NAGI_ENV	在 Nagi 管理的窗格进程内设为 1。
NAGI_PANE_ID	运行中窗格进程的公开窗格 id。
NAGI_TAB_ID	运行中窗格进程的公开标签页 id。
NAGI_WORKSPACE_ID	运行中窗格进程的公开工作区 id。
NAGI_LOG	设置日志过滤,例如 NAGI_LOG=nagi=debug。
NAGI_DISABLE_SOUND	即使启用了声音通知也禁用声音播放。