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

CLI 参考

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

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

启动与状态

Section titled “启动与状态”
Terminal window
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 channel show            # 打印 stable 或 preview
herdr channel set preview     # 启用预览构建
herdr channel set stable      # 把 Linux/macOS 直接安装切回稳定版
herdr --version               # 打印版本

状态命令:

Terminal window
herdr status
herdr status server
herdr status client

服务器

Section titled “服务器”
Terminal window
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 在编辑本地覆盖后,把智能体检测清单重载到运行中的服务器。

通知

Section titled “通知”
Terminal window
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 只在通知实际显示时播放已有的完成音和需要关注音。

会话

Section titled “会话”
Terminal window
herdr session list [--json]
herdr session attach <name>
herdr session stop <name> [--json]
herdr session delete <name> [--json]

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

工作区

Section titled “工作区”
Terminal window
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 close <workspace_id>

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

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

Worktree

Section titled “Worktree”
Terminal window
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。

标签页

Section titled “标签页”
Terminal window
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>

窗格

Section titled “窗格”
Terminal window
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>

读取输出:

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

发送输入:

Terminal window
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 的别名被接受。

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

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

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

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

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

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

Terminal window
herdr pane report-metadata <pane_id> \
  --source ID \
  [--agent LABEL] \
  [--applies-to-source ID] \
  [--title TEXT|--clear-title] \
  [--display-agent TEXT|--clear-display-agent] \
  [--custom-status TEXT|--clear-custom-status] \
  [--state-label STATUS=TEXT] \
  [--clear-state-labels] \
  [--seq N] \
  [--ttl-ms N]

STATUS 是 idle、working、blocked、done 或 unknown 之一。--agent 是对权威智能体标签的守卫。--applies-to-source 是对活动生命周期权威来源的守卫。用 --display-agent 修改可见名称。

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

--source 和 --applies-to-source 必须不超过 80 个字符,并且只能包含 ASCII 字母、数字、冒号、点、下划线和连字符。--ttl-ms 让元数据自动过期,取值必须在 1 到 86400000 毫秒之间。想让元数据一直保留到被替换、清除或窗格关闭时,省略它。--seq 让 Herdr 忽略来自同一 --source 的过期上报;过期上报会被 API 接受,但被窗格状态忽略。

智能体

Section titled “智能体”
Terminal window
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 <target> <text>
herdr agent rename <target> <name>|--clear
herdr agent focus <target>
herdr agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
herdr agent attach <target> [--takeover]
herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
herdr agent explain <target> [--json|--verbose]
herdr 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 方法,升级 Herdr 后,请先重启或交接到更新后的服务器,再使用实时 explain。用 --file PATH --agent LABEL 可以改为在本地解释一份保存的样本。默认输出显示智能体、最终状态、清单来源和版本、匹配的规则及其区域证据,以及任何回退、跳过或警告原因。加 --verbose 可以看到可见证据标志、缓存的远程版本、本地覆盖的遮蔽情况、远程更新状态,以及带匹配器和区域证据的完整已评估规则列表。提交问题报告或写测试时加 --json。

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

直接终端附加

Section titled “直接终端附加”
Terminal window
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 默认的外层终端窗口标题。

等待

Section titled “等待”

等待窗格中的输出:

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

等待窗格的智能体状态:

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

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

集成

Section titled “集成”
Terminal window
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 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 qodercli
herdr integration uninstall cursor
herdr integration status [--outdated-only]

插件

Section titled “插件”

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

安装、列出和移除插件:

Terminal window
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。

本地开发:

Terminal window
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 范围内。

配置目录:

Terminal window
herdr plugin config-dir <plugin_id>

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

动作:

Terminal window
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 也不会有歧义。

日志:

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

托管终端窗格:

Terminal window
herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|split|tab|zoomed] [--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,在活动窗格上方打开一个临时的缩放覆盖层。它也可以作为分割、新标签页或缩放窗格打开。非终端的原生插件窗格是之后的能力面。

--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 管理的变量保持权威。

读取来源

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

环境变量

Section titled “环境变量”
变量用途
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即使启用了声音通知也禁用声音播放。