--- title: CLI reference description: Herdr commands for sessions, workspaces, tabs, panes, notifications, agents, waits, integrations, and status. --- Herdr’s CLI talks to the running server over the same local socket API used by integrations and agents. Most commands print JSON responses. Use them from scripts when you want deterministic automation. ## Launch and status ```bash herdr # launch or attach to the default session herdr --session work # launch or attach to a named session herdr --remote workbox # attach through SSH, using local keybindings herdr --remote workbox --remote-keybindings server herdr --remote workbox --handoff herdr --no-session # single-process escape hatch herdr --default-config # print default config herdr update # download and install from the configured channel herdr update --handoff # opt into live handoff for supported running servers herdr channel show # print stable or preview herdr channel set preview # opt into preview builds herdr channel set stable # return Linux/macOS direct installs to stable herdr --version # print version ``` Status commands: ```bash herdr status herdr status server herdr status client ``` ## Server ```bash 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` runs the headless server explicitly. Use it for supervised or service-style setups. `reload-config` applies reloadable settings without restarting panes. `agent-manifests` shows the active agent detection manifest sources, cached remote versions, and last remote update results. `update-agent-manifests` fetches remote manifest updates immediately, reloads them into the running server, and prints the updated manifest status; pass `--json` for the raw status response. `reload-agent-manifests` reloads agent detection manifests into the running server after local override edits. ## Notifications ```bash herdr notification show [--body TEXT] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request] ``` `notification show` uses the configured `[ui.toast]` delivery. `--position` only affects in-app Herdr toasts. `--sound` defaults to `none`; `done` and `request` play the existing finished and needs-attention sounds only when the notification is shown. ## Sessions ```bash herdr session list [--json] herdr session attach <name> herdr session stop <name> [--json] herdr session delete <name> [--json] ``` Use `default` as the session name when you need to stop the default session explicitly. ## Workspaces ```bash herdr workspace list herdr workspace create [--cwd PATH] [--label TEXT] [--focus] [--no-focus] herdr workspace get <workspace_id> herdr workspace focus <workspace_id> herdr workspace rename <workspace_id> <label> herdr workspace close <workspace_id> ``` Create a workspace without stealing focus: ```bash herdr workspace create --cwd ~/project --label api --no-focus ``` ## Worktrees ```bash 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] ``` Worktrees are normal Herdr workspaces with Git checkout provenance. `worktree create` creates a Git worktree checkout, opens it as a workspace, and groups it with the parent repo workspace. Without `--path`, Herdr creates the checkout under `<worktrees.directory>/<repo>/<branch-slug>`. `workspace close` closes Herdr state only. `worktree remove` is the explicit checkout deletion path; it runs `git worktree remove`, never deletes the branch, and requires `--force` when Git refuses a dirty checkout. ## Tabs ```bash herdr tab list [--workspace <workspace_id>] herdr tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--focus] [--no-focus] herdr tab get <tab_id> herdr tab focus <tab_id> herdr tab rename <tab_id> <label> herdr tab close <tab_id> ``` ## Panes ```bash herdr pane list [--workspace <workspace_id>] herdr pane get <pane_id> herdr pane layout [--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] [--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 close <pane_id> ``` Read output: ```bash 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 ``` Send input: ```bash herdr pane send-text <pane_id> <text> herdr pane send-keys <pane_id> <key> [key ...] herdr pane run <pane_id> <command> ``` `pane run` submits text plus Enter atomically. Prefer it over `send-text` plus `send-keys Enter` for commands. Report agent state from custom hooks: ```bash 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`, and `agent list` include a read-only `agent_session` object when an official integration has reported a native session reference. If no native session reference is stored, the field is omitted. Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The existing `cwd` field remains the pane/workspace cwd used for labels and follow-cwd behavior. Report display-only pane metadata without taking over semantic state: ```bash 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` is one of `idle`, `working`, `blocked`, `done`, or `unknown`. `--agent` is a guard for the authoritative agent label. `--applies-to-source` is a guard for the active lifecycle authority source. Use `--display-agent` to change the visible name. ## Agents ```bash 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] [--focus|--no-focus] -- <argv...> herdr agent explain <target> [--json|--verbose] herdr agent explain --file PATH --agent LABEL [--json|--verbose] ``` Agent targets can be terminal IDs, unique agent names, detected or reported agent labels, or legacy pane IDs. Names and labels are agent identities. Terminal IDs and legacy pane IDs are low-level escape hatches. `agent read` reads the resolved terminal stream. `agent send` writes literal text to that stream. `agent get`, `agent focus`, `agent wait`, and `agent attach` require the resolved terminal to have agent identity. `agent rename` can assign that identity. `agent explain` asks the running server to classify the same bottom-buffer detection snapshot used by screen detection, so live output reflects the server's active manifest cache. Because this uses the `agent.explain` socket method, restart or hand off to an updated server after upgrading Herdr before using live explain. Use `--file PATH --agent LABEL` to explain a saved fixture locally instead. The default output shows the agent, final state, manifest source and version, matched rule with its region evidence, and any fallback, skip, or warning reasons. Add `--verbose` for visible evidence flags, cached remote version, local override shadowing, remote update status, and the full evaluated-rules list with matcher and region evidence. Add `--json` for issue reports or tests. Use `pane send-text`, `pane send-keys`, `pane run`, and `terminal attach` for ordinary terminals, servers, tests, shells, or low-level terminal control. Use `pane run` when you want to submit a command with Enter. ## Direct terminal attach ```bash herdr terminal attach <terminal_id> [--takeover] ``` Detach from direct attach with `ctrl+b q`. Send literal `ctrl+b` with `ctrl+b ctrl+b`. ## Waits Wait for output in a pane: ```bash herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw] ``` Wait for pane agent state: ```bash herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS] ``` Use `wait output` for normal commands and servers. Use `wait agent-status` for coding agents. ## Integrations ```bash herdr integration install pi herdr integration install omp herdr integration install claude herdr integration install codex herdr integration install copilot 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 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] ``` ## Read sources | Source | Meaning | | --- | --- | | `visible` | Current rendered screen. Best for UI feedback loops. | | `recent` | Recent scrollback with terminal wrapping. | | `recent-unwrapped` | Recent scrollback without soft wrapping. Best for logs. | | `detection` | Bottom-buffer snapshot used by agent screen detection. | ## Environment variables | Variable | Purpose | | --- | --- | | `HERDR_CONFIG_PATH` | Override the config file path. | | `HERDR_SESSION` | Select a named session for CLI commands. | | `HERDR_SOCKET_PATH` | Low-level socket path override. | | `HERDR_LOG` | Set log filter, for example `HERDR_LOG=herdr=debug`. | | `HERDR_DISABLE_SOUND` | Disable sound playback even when sound notifications are enabled. |