本页面的翻译由 LLM 生成。如果你发现翻译有误,请在 GitHub 上提交 issue 告诉我们。

CLI 参考

Next docs describe unreleased work from master. Stable docs remain at /docs/.

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

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

启动与状态

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

状态命令:

herdr status
herdr status server
herdr status client

API schema 命令:

herdr api schema
herdr api schema --json
herdr api schema --output herdr-api.schema.json

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

Shell 补全

herdr completion zsh
herdr completions zsh
herdr completion bash
herdr completion fish
herdr completion powershell
herdr completion elvish

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

source <(herdr completion zsh)

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

mkdir -p ~/.zfunc
herdr completion zsh > ~/.zfunc/_herdr

然后确认 .zshrc 包含:

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

服务器

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

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

通知

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

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

会话

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

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

工作区

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

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

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

工作区是顶层项目或工作上下文。创建工作区也会创建第一个标签页和根窗格。JSON 响应中的 .result.workspace.workspace_id、.result.tab.tab_id 和 .result.root_pane.pane_id 是对应 ID。

Worktree

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

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

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

标签页

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

标签页是工作区内的另一个终端布局。不指定 --workspace 时,tab create 使用活动工作区;如果没有活动工作区则失败。JSON 响应中的 .result.tab.tab_id 和 .result.root_pane.pane_id 是对应 ID。

创建工作区、标签页和拆分窗格默认不改变焦点。--focus 选择新布局;--no-focus 显式表达默认行为。不指定 --cwd 时,新终端遵循 terminal.new_cwd 设置,默认跟随来源窗格或工作区。每个 --env KEY=VALUE 在新的根 shell 中添加或替换一个环境变量。

窗格

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

接受 --current 的窗格命令在 Herdr 窗格内运行时使用调用方的 HERDR_PANE_ID。对 pane split 而言,显式窗格 ID 或 --pane ID 拆分该窗格,--current 拆分调用方窗格,省略目标则使用 UI 当前聚焦的窗格。拆分响应中的新窗格 ID 位于 .result.pane.pane_id。

执行 pane move 后,后续命令应使用 .result.move_result.pane.pane_id。跨工作区移动会改变带工作区前缀的窗格 ID;旧值保留在 .result.move_result.previous_pane_id。运行中进程的 HERDR_PANE_ID、HERDR_TAB_ID 和 HERDR_WORKSPACE_ID 保持启动时的值,但 Herdr 会把旧窗格 ID 保留为该终端的别名,所以使用 --current 的窗格命令仍能解析它。实时智能体名称也会跟随终端。

读取输出:

herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
herdr pane read <pane_id> --source visible --ansi
herdr pane read <pane_id> --source recent-unwrapped --lines 120

pane read 直接打印 UTF-8 终端文本。默认去除 ANSI 转义;来源包含样式时,使用 --format ansi 或 --ansi 保留。detection 来源始终是纯文本。对 recent 类来源,--lines N 会在可选的取消折行之前选择最后 N 个已渲染终端行;省略时默认读取 80 行。对 visible 和 detection,省略 --lines 会返回完整快照,指定时保留按换行分隔的最后 N 行。agent read 使用相同的输出和行数行为。

发送输入:

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

<key> 使用 Herdr 的组合键语法: 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 的别名被接受。

标准拼写是 esc;也接受 escape。

pane run 会遵循当前的 bracketed paste 模式,并把文本和 Enter 作为一个原子操作提交。发送命令时优先用它,而不是 send-text 加 send-keys Enter;单独的发送操作仍是底层操作,不会提交命令。

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

herdr 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]

herdr pane report-agent-session <pane_id> \
  --source ID \
  --agent LABEL \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path PATH] \
  [--session-start-source SOURCE]

herdr pane release-agent <pane_id> \
  --source ID \
  --agent LABEL \
  [--seq N]

report-agent-session 只更新原生会话身份,不上报生命周期状态。release-agent 在智能体进程退出时结束该来源的生命周期权威。

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

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

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

herdr 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 修改可见名称。

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

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

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

智能体

窗格与智能体的模型和完整协调示例见智能体自动化。

herdr agent list
herdr agent get <target>
herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
herdr agent send-keys <target> <key> [key ...]
herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
herdr agent rename <target> <name>|--clear
herdr agent focus <target>
herdr agent wait <target> [--until STATUS]... [--timeout MS]
herdr agent attach <target> [--takeover]
herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
herdr agent explain <target> [--json|--verbose]
herdr agent explain --file PATH --agent LABEL [--json|--verbose]

智能体目标只能是唯一的实时智能体名称,或当前承载该智能体的窗格 ID。终端 ID 和单独的智能体 kind 标签不能作为目标。通过 agent start 启动的智能体必须有名称;手动启动的智能体保持未命名,通过窗格 ID 寻址。

agent start 会在现有可用 shell 窗格中启动智能体:交互式 shell 必须占用前台,不能有正在前台运行的命令、编辑器或智能体。拓扑必须单独创建。名称在实时智能体中必须唯一,并匹配 [a-z][a-z0-9_-]{0,31}。支持的 kind 是 pi、claude、codex、gemini、cursor、devin、agy、cline、omp、mastracode、opencode、copilot、kimi、kiro、droid、amp、grok、hermes、kilo、qodercli 和 maki。名称属于当前窗格占用者,在该智能体退出、release 或被替换时清除;短暂的检测不确定不会清除它。

start 只有在预期智能体占用同一终端并可接受交互输入后才返回。默认启动超时是 30000 毫秒;显式值必须大于 3000 且不超过 300000。

agent prompt 遵循当前的 bracketed paste 模式，即使智能体处于 working 也会原子地提交文本和编码后的 Enter。使用 --wait 时，从非 working 状态发送的提示必须在五秒内产生可观察的生命周期变化，否则 Herdr 返回 agent_prompt_stalled；调用方超时不超过五秒时，仍返回普通的 timeout 错误。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。--until 用于缩小匹配状态，不带 --wait 时会被拒绝。独立的 agent wait 在当前状态匹配时立即返回。两者默认匹配 idle、done 或 blocked；需要 unknown 时请明确使用 --until unknown。

idle 表示智能体在等待输入,且其标签页已在聚焦的 Herdr 界面中显示。done 是相同的底层 idle 状态,用于未查看的后台工作完成后。聚焦该标签页或用 pane focus / agent focus 指向它会标记为已查看;仅通过 CLI 读取不会改变它。blocked 表示 Herdr 识别到审批或提问界面。unknown 表示智能体存在但无法可靠分类,不代表工作成功。

agent send-keys 发送 enter、up、esc、ctrl+c 等逻辑按键。Herdr 会在写入任何字节前验证所有按键。agent read 读取解析出的终端流,agent rename 为已检测到的智能体命名。

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

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

直接终端附加

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

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

输出等待

等待窗格中的输出:

herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]

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

pane wait-output 会立即检查所选快照,所以已经存在的输出也能匹配。默认来源名是 recent;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。--lines 可以修改这个行数限制。--match 在单行中查找字面子串;--regex 使用 Rust 正则表达式语法并逐行匹配。

pane wait-output、agent wait 和 agent prompt --wait 在省略 --timeout 时会无限等待。超时或服务器错误以 JSON 写到 stderr,退出状态为 1。CLI 用法错误的退出状态为 2。

集成

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

插件

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

安装、列出和移除插件:

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

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

本地开发:

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

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

配置目录:

herdr plugin config-dir <plugin_id>

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

动作:

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

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

日志:

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

托管终端窗格:

herdr 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]
herdr plugin pane focus <pane_id>
herdr plugin pane close <pane_id>

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

--env KEY=VALUE 可以在启动进程的命令上重复使用,只作用于新启动的进程。当与调用方提供的环境变量冲突时,HERDR_SOCKET_PATH、HERDR_BIN_PATH、HERDR_ENV、HERDR_WORKSPACE_ID、HERDR_TAB_ID、HERDR_PANE_ID、HERDR_PLUGIN_ID、HERDR_PLUGIN_ROOT、HERDR_PLUGIN_CONFIG_DIR、HERDR_PLUGIN_STATE_DIR、HERDR_PLUGIN_ENTRYPOINT_ID 和 HERDR_PLUGIN_CONTEXT_JSON 等 Herdr 管理的变量保持权威。

读取来源

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

此表描述读取时的含义。仅对 pane wait-output 而言,recent 和 recent-unwrapped 都搜索 recent 的未折行快照,默认写法仍是 recent。

环境变量

变量	用途
`HERDR_CONFIG_PATH`	覆盖配置文件路径。
`HERDR_SESSION`	为 CLI 命令选择命名会话。
`HERDR_SOCKET_PATH`	底层 socket 路径覆盖。
`HERDR_ENV`	在 Herdr 管理的窗格进程内设为 `1`。
`HERDR_PANE_ID`	运行中窗格进程的公开窗格 id。
`HERDR_TAB_ID`	运行中窗格进程的公开标签页 id。
`HERDR_WORKSPACE_ID`	运行中窗格进程的公开工作区 id。
`HERDR_LOG`	设置日志过滤,例如 `HERDR_LOG=herdr=debug`。
`HERDR_DISABLE_SOUND`	即使启用了声音通知也禁用声音播放。