14 第 12 章 CLI 完整参考
14.1 概述
本章是 Herdr 命令行界面的完整参考手册。所有命令按功能分组，每条命令附带语法说明和示例代码。你可以把本章当作速查表——遇到不确定的选项时，直接跳到对应章节。
Tip
阅读指南：本章按功能模块组织，不需要从头读到尾。建议先浏览目录找到你需要的功能区域，再查阅具体命令。
14.2 启动与状态
14.2.1 herdr
启动 Herdr 应用（如果已在运行，则聚焦到前台）。
# 启动 Herdr
herdr
# 后台启动（不自动聚焦）
herdr --background14.2.2 herdr status
显示 Herdr 当前运行状态。
# 文本格式（默认）
herdr status
# JSON 格式
herdr status --json输出示例：
Herdr v1.2.3 (channel: stable)
Server: running (PID: 54321)
Uptime: 2h 15m
Workspaces: 3 (2 active)
Agents: 5 (3 working, 2 idle)14.2.3 herdr --version
显示版本号。
herdr --version
# Herdr 1.2.314.2.4 herdr --default-config
输出默认配置文件的完整 JSON。用于初始化或参考。
# 输出到终端
herdr --default-config
# 保存为配置文件
herdr --default-config > ~/.config/herdr/config.json14.3 更新与频道
14.3.1 herdr update
检查并安装更新。
# 检查是否有更新
herdr update --check
# 执行更新
herdr update
# 强制更新（即使已是最新版）
herdr update --force14.3.2 herdr channel show
显示当前更新频道。
herdr channel show
# current: stable14.3.3 herdr channel set
切换更新频道。
# 切换到 beta 频道
herdr channel set beta
# 切换回 stable
herdr channel set stable
# 切换到 nightly（获取最新特性）
herdr channel set nightly| 频道 | 稳定性 | 更新频率 | 适用场景 |
|---|---|---|---|
stable |
⭐⭐⭐ 最高 | 每月 | 日常使用 |
beta |
⭐⭐ 中等 | 每周 | 尝试新特性 |
nightly |
⭐ 最低 | 每日 | 开发者 / 调试 |
14.4 Shell 补全
14.4.1 herdr completion
生成 Shell 自动补全脚本。
# Zsh（推荐）
herdr completion zsh > ~/.zfunc/_herdr
# Bash
herdr completion bash > /etc/bash_completion.d/herdr
# Fish
herdr completion fish > ~/.config/fish/completions/herdr.fish安装后需要重启 Shell 或执行 source 使补全生效。
Note
Zsh 用户：如果你使用 Oh My Zsh，可以将补全文件放到 ~/.oh-my-zsh/custom/plugins/herdr/ 目录下。
14.5 Server
Herdr 的后台服务进程，负责管理所有工作空间、窗格和 Agent。
14.5.1 herdr server stop
停止后台 Server。
# 优雅停止（等待所有任务完成）
herdr server stop
# 强制停止
herdr server stop --force14.5.2 herdr server reload-config
重新加载配置文件，无需重启 Server。
herdr server reload-config
Tip
何时使用：修改 config.json 后，使用此命令热加载配置，不影响正在运行的 Agent。
14.5.3 herdr server update-agent-manifests
更新 Agent 清单（Agent 类型注册表）。
herdr server update-agent-manifests14.6 通知
14.6.1 herdr notification show
显示最近的通知（Agent 完成任务、请求审批等）。
# 显示所有通知
herdr notification show
# 只显示未读通知
herdr notification show --unread
# JSON 格式
herdr notification show --json14.7 Session
Session 代表一个用户与 Herdr 的交互会话。
14.7.1 herdr session list
列出所有会话。
herdr session list14.7.2 herdr session attach
附加到指定会话。
# 通过 ID 附加
herdr session attach abc-123
# 通过名称附加
herdr session attach "work-session"14.7.3 herdr session stop
停止指定会话。
herdr session stop abc-12314.7.4 herdr session delete
删除指定会话（不可恢复）。
herdr session delete abc-12314.8 Workspace
工作空间是 Herdr 的顶层组织单元。
14.8.1 herdr workspace create
创建新工作空间。
# 创建空工作空间
herdr workspace create "my-project"
# 从模板创建
herdr workspace create "my-project" --template layouts/fullstack.json
# 在指定目录创建
herdr workspace create "my-project" --cwd ~/projects/my-app14.8.2 herdr workspace list
列出所有工作空间。
herdr workspace list
# JSON 格式
herdr workspace list --json14.8.3 herdr workspace get
获取指定工作空间的详细信息。
herdr workspace get "my-project"14.8.4 herdr workspace focus
切换到指定工作空间。
herdr workspace focus "my-project"14.8.5 herdr workspace rename
重命名工作空间。
herdr workspace rename "old-name" "new-name"14.8.6 herdr workspace close
关闭工作空间（释放资源，不删除）。
herdr workspace close "my-project"14.8.7 herdr workspace report-metadata
报告工作空间的元数据（用于自动化和集成）。
herdr workspace report-metadata "my-project" --json14.9 Worktree
Worktree 是工作空间内的 Git Worktree 集成，支持在不同窗格中操作同一仓库的不同分支。
14.9.1 herdr worktree create
# 在当前工作空间创建 worktree
herdr worktree create feature-auth
# 指定基础分支
herdr worktree create feature-auth --base develop14.9.2 herdr worktree list
herdr worktree list14.9.3 herdr worktree open
在窗格中打开 worktree。
# 在指定窗格打开
herdr worktree open feature-auth --pane p214.9.4 herdr worktree remove
移除 worktree。
herdr worktree remove feature-auth14.10 Tab
Tab 是工作空间内的标签页，每个 Tab 有独立的布局。
14.10.1 herdr tab create
# 创建新 Tab
herdr tab create "tests"
# 创建并自动切换
herdr tab create "tests" --focus14.10.2 herdr tab list
herdr tab list14.10.3 herdr tab get
herdr tab get "tests"14.10.4 herdr tab focus
herdr tab focus "tests"
# 通过索引切换
herdr tab focus 214.10.5 herdr tab rename
herdr tab rename "old-name" "new-name"14.10.6 herdr tab close
herdr tab close "tests"14.11 Pane（完整参考）
Pane 是终端窗格——Herdr 中最核心的操作单元。本节完整列出所有 Pane 子命令。
14.11.1 herdr pane split
分割窗格。
# 水平分割（左右）
herdr pane split p1 --direction horizontal
# 垂直分割（上下）
herdr pane split p1 --direction vertical
# 指定比例
herdr pane split p1 --direction horizontal --ratio 0.314.11.2 herdr pane swap
交换两个窗格的位置。
herdr pane swap p1 p214.11.3 herdr pane move
移动窗格到新位置。
# 向左移动
herdr pane move p1 --left
# 向右移动
herdr pane move p1 --right
# 向上移动
herdr pane move p1 --up
# 向下移动
herdr pane move p1 --down14.11.4 herdr pane close
关闭窗格。
herdr pane close p3
# 强制关闭（即使有运行中的进程）
herdr pane close p3 --force14.11.5 herdr pane read
读取窗格内容。
# 可见区域
herdr pane read p1 --source visible
# 最近输出（默认 80 行）
herdr pane read p1 --source recent
# 指定行数
herdr pane read p1 --source recent --lines 20014.11.6 herdr pane send-text
向窗格发送文本（不自动回车）。
# 发送文本
herdr pane send-text p1 -- "echo hello"
# 发送并回车
herdr pane send-text p1 -- "echo hello"
herdr pane send-keys p1 -- Enter14.11.7 herdr pane send-keys
发送特殊按键。
# 回车
herdr pane send-keys p1 -- Enter
# Ctrl+C
herdr pane send-keys p1 -- C-c
# Escape
herdr pane send-keys p1 -- Escape
# Tab
herdr pane send-keys p1 -- Tab
# 方向键
herdr pane send-keys p1 -- Up
herdr pane send-keys p1 -- Down
Note
支持的按键名称：Enter、Escape、Tab、Backspace、Up、Down、Left、Right、Home、End、PageUp、PageDown、Space。Ctrl 组合键格式为 C-<key>（如 C-c、C-d、C-z）。Alt 组合键格式为 M-<key>。
14.11.8 herdr pane run
在窗格中执行命令并等待完成。
# 执行命令
herdr pane run p1 -- "git status"
# 设置超时
herdr pane run p1 --timeout 30 -- "npm test"
# 捕获 stdout 到变量
result=$(herdr pane run p1 -- "ls -la")14.11.9 herdr pane wait-output
等待窗格输出匹配指定模式。
# 等待字符串出现
herdr pane wait-output p1 --pattern "done"
# 等待正则匹配
herdr pane wait-output p1 --pattern-regex "(PASS|FAIL)"
# 设置超时（秒）
herdr pane wait-output p1 --pattern "ready" --timeout 6014.11.10 herdr pane report-agent
报告窗格中 Agent 的状态信息。
herdr pane report-agent p214.11.11 herdr pane report-metadata
报告窗格的元数据。
herdr pane report-metadata p2 --json14.11.12 herdr pane focus
聚焦到指定窗格。
herdr pane focus p214.11.13 herdr pane resize
调整窗格大小。
# 向右扩展 10%
herdr pane resize p1 --right 10
# 向下扩展 5%
herdr pane resize p1 --down 5
# 直接设置比例
herdr pane resize p1 --ratio 0.414.11.14 herdr pane zoom
切换窗格的放大状态。
# 放大（填满整个 Tab）
herdr pane zoom p1
# 再次执行恢复
herdr pane zoom p114.11.15 herdr pane rename
重命名窗格（设置别名）。
herdr pane rename p1 "editor"14.11.16 herdr pane layout
对窗格应用预设布局。
# 水平等分
herdr pane layout even-horizontal
# 垂直等分
herdr pane layout even-vertical
# 主-从布局
herdr pane layout main-horizontal
herdr pane layout main-vertical
# 平铺布局
herdr pane layout tiled14.11.17 herdr pane process-info
显示窗格中运行的进程信息。
herdr pane process-info p114.11.18 herdr pane neighbor
查询窗格的邻居。
# 查看右边的邻居
herdr pane neighbor p1 --direction right
# 查看所有邻居
herdr pane neighbor p1 --all14.11.19 herdr pane edges
查询窗格的边界信息。
herdr pane edges p114.12 Agent
14.12.1 herdr agent start
启动 AI Agent。
herdr agent start [--pane <id>] [--kind <kind>] [--timeout <sec>] <name> [-- <args>]详见第 11 章。
14.12.2 herdr agent prompt
向 Agent 发送提示。
# 异步发送
herdr agent prompt my-helper -- "修复 bug"
# 同步等待回复
herdr agent prompt --wait my-helper -- "hello"
# 带超时
herdr agent prompt --wait my-helper --timeout 120 -- "分析代码"14.12.3 herdr agent wait
等待 Agent 进入指定状态。
# 等待完成
herdr agent wait my-helper --until done
# 等待空闲或阻塞
herdr agent wait my-helper --until idle --until blocked
# 带超时
herdr agent wait my-helper --until done --timeout 60014.12.4 herdr agent read
读取 Agent 输出。
# 最近输出
herdr agent read my-helper --source recent
# 可见区域
herdr agent read my-helper --source visible
# 指定行数
herdr agent read my-helper --source recent --lines 5014.12.5 herdr agent get
获取 Agent 状态信息。
# 文本格式
herdr agent get my-helper
# JSON 格式
herdr agent get my-helper --format json14.12.6 herdr agent list
列出所有 Agent。
herdr agent list
# 只列出指定状态的 Agent
herdr agent list --state working
herdr agent list --state idle
# JSON 格式
herdr agent list --json14.12.7 herdr agent explain
解释 Agent 的当前行为（自然语言描述）。
herdr agent explain my-helper14.12.8 herdr agent send-keys
向 Agent 窗格发送特殊按键。
# 打断当前操作
herdr agent send-keys my-helper -- Escape
# Ctrl+C
herdr agent send-keys my-helper -- C-c14.12.9 herdr agent rename
重命名 Agent。
herdr agent rename old-name new-name14.12.10 herdr agent focus
聚焦到 Agent 所在的窗格。
herdr agent focus my-helper14.12.11 herdr agent attach
附加到 Agent 的交互式会话（进入 Agent 所在窗格的全屏模式）。
herdr agent attach my-helper14.13 Integration
Herdr 可以与外部系统集成（Shell 集成、IDE 集成等）。
14.13.1 herdr integration install
安装集成。
# 安装 VS Code 集成
herdr integration install vscode
# 安装 Shell 集成
herdr integration install shell
# 安装 iTerm2 集成
herdr integration install iterm214.13.2 herdr integration uninstall
卸载集成。
herdr integration uninstall vscode14.13.3 herdr integration status
查看集成状态。
herdr integration status14.14 Plugin
插件系统允许第三方扩展 Herdr 的功能。
14.14.1 herdr plugin install
从注册表安装插件。
herdr plugin install @user/herdr-theme-dark14.14.2 herdr plugin link
本地开发模式——链接到本地插件目录。
herdr plugin link ~/dev/my-herdr-plugin14.14.3 herdr plugin uninstall
卸载插件。
herdr plugin uninstall @user/herdr-theme-dark14.14.4 herdr plugin unlink
取消本地插件链接。
herdr plugin unlink my-plugin14.14.5 herdr plugin list
列出已安装的插件。
herdr plugin list
# 显示详细信息
herdr plugin list --verbose14.14.6 herdr plugin config-dir
显示插件配置目录路径。
herdr plugin config-dir
# ~/.config/herdr/plugins14.14.7 herdr plugin action.list
列出插件提供的 Action。
herdr plugin action.list my-plugin14.14.8 herdr plugin action.invoke
调用插件的 Action。
herdr plugin action.invoke my-plugin --action "format-code" --args '{"lang": "ts"}'14.14.9 herdr plugin log.list
查看插件日志。
herdr plugin log.list my-plugin
# 只看最近的 10 条
herdr plugin log.list my-plugin --limit 1014.14.10 herdr plugin pane.open
由插件打开一个新窗格。
herdr plugin pane.open my-plugin --title "Plugin Output"14.14.11 herdr plugin pane.focus
由插件聚焦窗格。
herdr plugin pane.focus my-plugin --pane-id p214.14.12 herdr plugin pane.close
由插件关闭窗格。
herdr plugin pane.close my-plugin --pane-id p214.15 Terminal
14.15.1 herdr terminal attach
附加到外部终端会话（如 SSH 会话）。
herdr terminal attach my-ssh-session14.15.2 herdr terminal session
管理终端会话。
# 列出终端会话
herdr terminal session list
# 创建新终端会话
herdr terminal session create "remote-dev"14.16 Layout
14.16.1 herdr layout export
导出当前布局为 JSON。
# 导出到文件
herdr layout export > my-layout.json
# 导出指定 Tab 的布局
herdr layout export --tab "editor" > editor-layout.json14.16.2 herdr layout apply
应用布局文件。
# 应用布局
herdr layout apply my-layout.json
# 应用到指定 Tab
herdr layout apply my-layout.json --tab "editor"14.16.3 herdr layout set-split-ratio
设置窗格分割比例。
# 设置比例（0.0 ~ 1.0）
herdr layout set-split-ratio p1 0.314.17 环境变量参考
Herdr 支持以下环境变量，按优先级从高到低排列（命令行参数 > 环境变量 > 配置文件）。
| 环境变量 | 说明 | 默认值 | 示例 |
|---|---|---|---|
HERDR_CONFIG |
配置文件路径 | ~/.config/herdr/config.json |
/custom/config.json |
HERDR_SOCKET |
Socket 路径 | 自动分配 | /tmp/herdr.sock |
HERDR_CHANNEL |
更新频道 | stable |
beta |
HERDR_LOG_LEVEL |
日志级别 | info |
debug、warn、error |
HERDR_LOG_FILE |
日志文件路径 | ~/.local/share/herdr/herdr.log |
/var/log/herdr.log |
HERDR_DATA_DIR |
数据目录 | ~/.local/share/herdr/ |
/custom/data |
HERDR_PLUGIN_DIR |
插件目录 | ~/.config/herdr/plugins |
/custom/plugins |
HERDR_DEFAULT_KIND |
默认 Agent 类型 | claude |
codex |
HERDR_DEFAULT_TIMEOUT |
默认 Agent 超时（秒） | 300 |
600 |
HERDR_SHELL |
默认 Shell | $SHELL |
/bin/zsh |
HERDR_EDITOR |
默认编辑器 | $EDITOR |
nvim |
HERDR_NO_COLOR |
禁用彩色输出 | 未设置 | 1 |
HERDR_FORCE_COLOR |
强制彩色输出 | 未设置 | 1 |
Tip
调试技巧：设置 HERDR_LOG_LEVEL=debug 可以在终端看到详细的内部日志，对于排查问题非常有用。
HERDR_LOG_LEVEL=debug herdr status14.18 退出码参考
所有 Herdr 命令遵循统一的退出码规范：
| 退出码 | 含义 | 说明 |
|---|---|---|
0 |
成功 | 命令正常完成 |
1 |
一般错误 | 命令执行失败 |
2 |
参数错误 | 命令行参数无效 |
3 |
配置错误 | 配置文件格式或值有误 |
4 |
连接错误 | 无法连接到 Server |
5 |
不存在 | 指定的资源（Pane/Agent 等）不存在 |
10 |
Agent 超时 | Agent 等待超时 |
11 |
Agent stalled | Agent 未在预期时间内响应 |
12 |
Agent blocked | Agent 被阻塞，需要人类介入 |
124 |
命令超时 | --timeout 触发 |
130 |
被中断 | 收到 SIGINT（Ctrl+C） |