Skip to content

CLI reference

Herdsman’s CLI talks to the running server over the same local socket API used by integrations and agents.

Most commands print JSON responses for deterministic automation in scripts.

Terminal window
herdsman # launch or attach to the default session
herdsman --remote workbox # attach through SSH, using local keybindings
herdsman --default-config # print default config
herdsman update # download and install from the configured channel
herdsman completion zsh # generate a zsh completion script
herdsman channel show # print stable or preview
herdsman channel set preview # opt into preview builds
herdsman channel set stable # return a direct install to stable
herdsman --version # print version

Optional launch and update settings:

  • Add --session <name> to use a named session instead of the default.
  • Add --remote-keybindings server to remote attach to use server keybindings instead of local ones.
  • Experimental live handoff requires explicit --handoff on herdsman --remote or herdsman update. It is not the normal setup or connection path; see Updates.

Status commands:

Terminal window
herdsman status
herdsman status server
herdsman status client

API schema commands:

Terminal window
herdsman api schema
herdsman api schema --json
herdsman api schema --output herdsman-api.schema.json

herdsman api schema prints a short summary of the socket protocol schema bundled with the installed binary. Use --json for the full JSON Schema document, or --output PATH to write that document to a file.

Terminal window
herdsman machine list
herdsman machine add workbox
herdsman machine add workbox --label "Build machine"
herdsman machine rename <profile-id> --label "New name"
herdsman machine disable <profile-id>
herdsman machine enable <profile-id>
herdsman machine remove <profile-id>

In an interactive terminal, machine add discovers running sessions and lets you choose when several are running. No running sessions, or no Herdsman installation, uses default; failed queries against an installed binary require an explicit choice. Add --remote-session <name> to skip discovery. Non-interactive commands use default unless that flag is supplied. machine list accepts optional --json for scripts. See Connecting machines for the full setup and connection guide.

machine add checks the remote installation’s capabilities, installs or updates with approval only when needed, and starts the requested session’s background server before saving. Compatible release versions do not need to match. Run setup in an interactive terminal when installation or restart approval is required; failed or cancelled setup does not save a profile. Replacing a running server requires explicit approval with a default answer of No, and stops its pane processes. machine add never enables experimental handoff implicitly.

Changes apply automatically to open local Herdsman clients, normally within a second. Added or enabled machines connect in the background; renaming does not reconnect. Removing or disabling disconnects only that machine and leaves its remote sessions running. Removing the machine you are viewing returns to Local, or shows Local as unavailable until it reconnects. Each profile stores an opaque ID, label, SSH target, explicit remote session, and enabled state in client state. Herdsman does not store passwords, private keys, or other SSH credentials.

Use herdsman machine status [<label-or-id>] [--json] for fresh, noninteractive SSH and remote Herdsman checks. reachable describes this check, not a TUI’s current connection. Use herdsman machine reconnect <label-or-id> in a terminal for SSH authentication and verification; it does not install or update Herdsman. Open clients retry failed connections within 30 seconds. Clicking ! auth or ! error shows the latest error and CLI guidance; collapsed sidebars show !. See Recovering SSH authentication for platform limits. For remote setup, use herdsman --remote workbox, adding --session <name> only for a named session.

Workspace, tab, pane IDs, and agent names belong to a single server. Selecting a machine in the UI does not retarget CLI commands. Use the global prefix --machine <label-or-id> to route API commands to a saved SSH machine:

Terminal window
herdsman --machine "Build machine" agent list
herdsman --machine <profile-id> pane list
herdsman --machine "Build machine" agent prompt w1:p1 "review this change"
herdsman --machine "Build machine" worktree create --cwd /srv/project --branch review

The selector must match an enabled saved profile ID or a unique, case-sensitive label, not an arbitrary SSH hostname. The saved remote session is used; combining --machine with --session or --remote is an error. Without the prefix, commands retain their existing local session/socket behavior.

Supported commands are workspace, worktree, tab, pane, notification, agent (except attach and local explain --file), api snapshot, status server, and API-backed plugin commands (link, unlink, enable, disable, list, action, log, pane). Server commands support stop, reload-config, agent-manifests, and reload-agent-manifests. Local installation/configuration commands, plugin installation, session management, and interactive terminal attachment are not forwarded.

Requests and responses travel through the JSON API over non-interactive SSH; API payloads are not interpolated into the SSH shell command. No open TUI is required, and the bridge never installs, starts, or restarts a server. Update the local CLI and remote Herdsman installation to support machine forwarding, and keep the running remote server’s API protocol compatible. Authentication, unavailable machines, and incompatible versions fail without falling back to Local. Requests are not automatically retried after connection failure.

Local pane IDs are not inherited by remote commands. Use explicit remote IDs; --current cannot refer to the caller’s local pane. Remote worktree paths must be absolute, ~, or start with ~/ (expanded on the server); plugin link paths must be absolute. The prefix targets one machine at a time; combined listings and routing through another TUI’s connections are not included.

Terminal window
herdsman completion zsh
herdsman completions zsh
herdsman completion bash
herdsman completion fish
herdsman completion powershell
herdsman completion elvish

completion prints the script to stdout. completions is an alias. For a temporary zsh session, load the script directly:

Terminal window
source <(herdsman completion zsh)

For a persistent zsh setup, write the generated _herdsman function somewhere on your fpath before compinit runs:

Terminal window
mkdir -p ~/.zfunc
herdsman completion zsh > ~/.zfunc/_herdsman

Then make sure your .zshrc contains:

Terminal window
fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit
Terminal window
herdsman server
herdsman server stop
herdsman server reload-config
herdsman server agent-manifests [--json]
herdsman server update-agent-manifests [--json]
herdsman server reload-agent-manifests

herdsman 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.

Terminal window
herdsman notification show <title> [--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 Herdsman toasts. --sound defaults to none; done and request play the existing finished and needs-attention sounds only when the notification is shown.

Terminal window
herdsman session list [--json]
herdsman session attach <name>
herdsman session stop <name> [--json]
herdsman session delete <name> [--json]

Use default as the session name when you need to stop the default session explicitly.

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

Create a workspace without stealing focus:

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

A workspace is a top-level project or work context. Creating one also creates its first tab and root pane. The JSON response exposes their IDs as .result.workspace.workspace_id, .result.tab.tab_id, and .result.root_pane.pane_id.

Terminal window
herdsman worktree list [--workspace ID | --cwd PATH] [--trust-repository]
herdsman worktree create [--workspace ID | --cwd PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--trust-repository]
herdsman worktree open [--workspace ID | --cwd PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--trust-repository]
herdsman worktree remove --workspace ID [--force] [--trust-repository]

Worktrees are normal Herdsman 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. If --branch names an existing local branch, Herdsman checks it out; otherwise it creates the branch from --base or HEAD. Without --path, Herdsman creates the checkout under <worktrees.directory>/<repo>/<branch-slug>.

workspace section puts a linked worktree’s workspace into a section, a named group within its repository, or takes it out with --clear. The sidebar nests each section under its repository; members report the name as their worktree_group token. workspace group, the command’s first name, still works.

workspace close closes only Herdsman state. Closing a primary workspace while linked-worktree workspaces are open requires --group; without it, the command leaves the group open and returns workspace_group_close_required. To delete the checkout, run worktree remove. It runs git worktree remove, never deletes the branch, and requires --force when Git refuses a dirty checkout.

Git rejects repositories owned by another user by default. If you have independently verified the repository, pass --trust-repository to trust its resolved path for that command only. Herdsman does not change your Git configuration.

Terminal window
herdsman tab list [--workspace <workspace_id>]
herdsman tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
herdsman tab get <tab_id>
herdsman tab focus <tab_id>
herdsman tab rename <tab_id> <label>
herdsman tab equalize width|height [<tab_id>|--current]
herdsman tab close <tab_id>

A tab is another terminal layout inside a workspace. Without --workspace, tab create uses the active workspace and fails if none exists. Its JSON response exposes .result.tab.tab_id and .result.root_pane.pane_id. Closing a workspace’s last tab also closes the workspace, matching the TUI close-tab action. If confirm_close is enabled and closing the tab would also close a whole worktree group, tab close returns a confirmation_required error instead.

tab equalize width gives every column in the tab the same width and leaves heights alone; tab equalize height does the same for rows. Without a tab ID it acts on the active tab, and --current picks the caller’s own tab. A pane above or below split columns spans them, so the narrowest columns end up equal.

With ui.confirm_close enabled, the TUI asks for confirmation before closing a workspace’s last tab or its only pane from a keybinding or the tab/pane menu. Ordinary pane closes and CLI/API closes remain immediate.

Workspace and tab creation, and pane splitting, leave focus unchanged by default. --focus selects the new layout; --no-focus states the default explicitly. Without --cwd, new terminals follow the configured terminal.new_cwd policy, which follows the source pane or workspace by default. Each --env KEY=VALUE adds or replaces that variable in the new root shell.

Terminal window
herdsman preset list
herdsman preset show <name>
herdsman preset save <name> [<tab_id>|--current] [--overwrite]
herdsman preset load <name> [--workspace <workspace_id>|--current] [--no-focus]
[--param <name>=<value>]...
herdsman preset edit <name>
herdsman preset rename <name> <new_name>
herdsman preset delete <name>

A preset is a tab’s layout saved under a name. preset save records the active tab, a tab by ID, or with --current the caller’s own tab; it refuses a name already taken unless --overwrite is given. preset load opens the preset as a new tab in the active workspace, a workspace by ID, or with --current the caller’s own workspace, and focuses it unless --no-focus is given. Its panes start in the workspace’s folder, and each pane’s command is typed into its shell. --param gives a value for one of the preset’s parameters; every pane gets it as an environment variable, PR for pr. preset list includes presets whose file does not parse, with their error; preset show prints one preset’s tree and file path. preset edit opens the file in $VISUAL or $EDITOR and checks it when the editor closes. Every command but edit also works with --machine.

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

For pane commands that accept --current, Herdsman uses the calling pane’s HERDSMAN_PANE_ID when the command runs inside a Herdsman pane. For pane split, an explicit pane id or --pane ID splits that pane. An omitted target splits the calling pane when HERDSMAN_PANE_ID is available, otherwise the focused pane. --current requires a calling pane and errors when HERDSMAN_PANE_ID is unavailable. The split response exposes the new pane ID as .result.pane.pane_id.

pane input --right-click pane forwards unmodified right-click gestures to a mouse-reporting pane application. herdsman restores the default pane menu. Right-clicking the pane frame still opens Herdsman’s menu. pane split --right-click pane applies the same policy to the new pane at creation.

After pane move, use .result.move_result.pane.pane_id for later commands. A cross-workspace move changes the workspace-qualified pane ID; the prior value remains at .result.move_result.previous_pane_id. The running process keeps its launch-time HERDSMAN_PANE_ID, HERDSMAN_TAB_ID, and HERDSMAN_WORKSPACE_ID; Herdsman retains the old pane ID as an alias for that terminal, so pane commands using --current still resolve it. A live agent name follows the terminal and continues to resolve after the move.

Read output:

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

pane read prints UTF-8 terminal text directly. ANSI escapes are stripped by default; use --format ansi or --ansi to preserve them where the source exposes styling. The detection source is always plain text. For recent sources, --lines N selects the last N rendered terminal rows before optional unwrapping; without it, reads default to 80 rows. For visible and detection, omitting --lines returns the full snapshot, while specifying it keeps the last N newline-delimited lines. agent read uses the same output and line behavior.

Send input:

Terminal window
herdsman pane send-text <pane_id> <text>
herdsman pane send-keys <pane_id> <key> [key ...]
herdsman pane run <pane_id> <command>

<key> uses Herdsman key-combo syntax: plain printable keys such as a, special keys such as enter, tab, esc, backspace, left, right, up, and down, modifier chords such as ctrl+h, control+j, alt+x, and shift+tab, function keys such as f1, and named punctuation such as minus, plus, and backtick. Legacy C-c and c-c are accepted as aliases for ctrl+c. esc is the canonical spelling; escape is also accepted.

pane run honors live bracketed-paste mode and submits text plus Enter atomically. Prefer it over send-text plus send-keys Enter for commands; the separate send operations remain low-level and non-submitting.

Report agent state from custom hooks:

Terminal window
herdsman 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] \
[-- RESUME_COMMAND...]
herdsman pane report-agent-session <pane_id> \
--source ID \
--agent LABEL \
[--seq N] \
[--agent-session-id ID] \
[--agent-session-path PATH] \
[--session-start-source SOURCE] \
[-- RESUME_COMMAND...]
herdsman pane release-agent <pane_id> \
--source ID \
--agent LABEL \
[--seq N]

report-agent-session updates native session identity without reporting lifecycle state. release-agent ends that source’s lifecycle authority when its agent process exits.

Arguments after -- are the command Herdsman runs to resume this session after a server restart. The first argument must be a plain command name on PATH, and no argument may contain an apostrophe.

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 Herdsman can resolve the cwd of the foreground process controlling the pane. The cwd field remains the pane/workspace cwd used for labels and follow-cwd behavior.

pane get and pane list include scroll when terminal scroll metrics are available. scroll.offset_from_bottom == 0 means the pane is at the bottom of its scrollback.

Report display-only pane metadata without taking over semantic state:

Terminal window
herdsman 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 is one of idle, working, blocked, done, or unknown. --agent and --applies-to-source guard only --title, --display-agent, and --state-label. They do not guard token patches; token reporters own clearing or TTL refresh. Use --display-agent to change the visible name.

Metadata text is normalized before storage. Herdsman trims surrounding whitespace, removes control characters, and caps --title, --display-agent, each --state-label, and token values at 80 characters. Empty normalized token values clear that key.

--token patches one named display value; --clear-token removes one. Unmentioned tokens remain unchanged. Pane tokens are available to Agent sidebar rows as $name; workspace tokens are available to Space rows. TTL applies independently to the token keys updated by that call.

--source and --applies-to-source must be 80 characters or fewer and may contain only ASCII letters, digits, colon, dot, underscore, and hyphen. --ttl-ms makes metadata expire automatically and must be between 1 and 86400000 milliseconds. Omit it for metadata that should stay until replaced, cleared, or the pane closes. --seq lets Herdsman ignore stale reports from the same --source; stale reports are accepted by the API but ignored by pane state. A pane or workspace accepts sequenced token reports from at most 32 distinct sources during its lifetime; clearing or expiry does not release those source slots.

For the pane-versus-agent model and complete orchestration examples, see Agent automation.

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

Agent targets are either a unique live agent name or the pane ID that currently hosts the agent. Terminal IDs and bare agent-kind labels are not agent targets. Agents started through agent start require a name; manually launched agents remain unnamed and use their pane ID.

agent start activates an existing available shell pane: the pane’s interactive shell must own the foreground, with no foreground command, editor, or agent running. Topology must be created separately. Names are unique among live agents and must match [a-z][a-z0-9_-]{0,31}. The kind selects Herdsman’s canonical interactive executable, while arguments after -- are passed to that executable. Supported kinds are pi, claude, codex, gemini, cursor, devin, agy, cline, omp, mastracode, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qwen, letta, maki, and muse. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced. Temporary detection uncertainty does not clear it.

A successful start returns only after the expected agent owns the same terminal and is ready for interactive input. If detection reports blocked during startup, the command returns agent_not_ready immediately. The name remains available for agent read and agent send-keys, and becomes ready for prompts after detection reports idle. The default startup timeout is 30000 milliseconds; explicit values must be greater than 3000 and no more than 300000.

agent prompt honors live bracketed-paste mode and writes text followed by delayed Enter as one ordered submission, including while the agent is working. Success without --wait acknowledges the writes, not the start of a turn. On Windows, Codex receives a paste boundary before Enter so submission does not depend on prompt size; the caller timeout includes submission time. If the agent is already blocked, it returns agent_blocked without sending input. With --wait, a prompt sent from another non-working state has up to five seconds after submission to produce an observed working or blocked state or Herdsman returns agent_prompt_stalled; if the caller timeout expires first, Herdsman returns the normal timeout error. This prevents unrelated idle, done, or session changes from completing the wait. After activity is observed, it waits for the first requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. --until narrows the matching states and is rejected unless --wait is also present. Standalone agent wait returns immediately when the current status matches. Both default to idle, done, or blocked; use --until unknown explicitly when needed.

idle and done both mean ready for input. The CLI/API uses the server’s seen state: done is idle but not yet marked seen, explicit pane focus / agent focus commands mark the target seen, and reads do not. Each TUI client tracks viewed completions independently, so its Done badge can differ from the CLI or another client. blocked means Herdsman recognized an approval or question UI. unknown means an agent is present but Herdsman cannot classify it confidently, not that its work succeeded.

agent send-keys sends logical terminal keys such as enter, up, esc, or ctrl+c. Herdsman validates every key before writing any bytes. agent read reads the resolved terminal stream, and agent rename names an already detected agent.

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 Herdsman 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.

Terminal window
herdsman terminal attach <terminal_id> [--takeover]
herdsman terminal session control <target> [--takeover] [--cols N] [--rows N]
herdsman terminal session observe <target> [--cols N] [--rows N]
herdsman terminal title set <title>
herdsman terminal title clear

Detach from direct attach with ctrl+b q. Send literal ctrl+b with ctrl+b ctrl+b. terminal session control opens a writable live terminal stream for a pane, terminal, or agent target. It prints the same newline-delimited terminal.frame and terminal.closed records as observe mode. It reads newline-delimited JSON commands on stdin: terminal.input, terminal.resize, terminal.scroll, terminal.mouse, and terminal.release. One controller can own a terminal at a time; use --takeover to replace it. terminal.mouse sends one mouse event at a zero-based cell of the controller’s viewport, for example {"type":"terminal.mouse","action":"down","button":"left","column":12,"row":5}. action is down, up, drag, or move; button is left (default), right, or middle; modifiers is optional and combines Shift = 1, Ctrl = 2, and Alt = 4 (default 0). A click is down followed by up. Herdsman encodes the event for the application’s mouse mode and drops it when the application has not enabled mouse reporting, so a plain shell never receives stray input. move reaches only applications that track all mouse motion. terminal session observe opens a read-only live terminal stream for a pane, terminal, or agent target. It prints newline-delimited JSON terminal.frame records with base64-encoded ANSI bytes, then a terminal.closed record when the server closes the stream. Multiple observers can watch the same terminal without taking input, resize, scroll, or takeover authority. On Linux and macOS, an observer is disconnected if a socket write makes no progress for 30 seconds. A stalled stream can end without a final terminal.closed record; the pane and other clients keep running. Quiet panes do not trigger this timeout. terminal title clear hands the outer terminal window title back to ui.window_title.

Wait for output in a pane:

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

Use pane wait-output for normal commands and servers. Use agent wait for coding agents.

pane wait-output checks the selected snapshot immediately, including output that already exists, then polls until it matches. The default source name is recent; matching treats it as unwrapped recent output from the latest 80 rendered terminal rows. --lines changes that row limit. --match finds a literal substring on one line, and --regex uses Rust regular-expression syntax and also matches one line at a time.

A timeout or agent_prompt_stalled does not prove the prompt was never delivered. Inspect the agent before retrying.

pane wait-output and agent wait wait indefinitely when --timeout is omitted. For agent prompt --wait, the settled-state wait is indefinite after activity is observed or when the prompt starts in working; a non-working prompt still returns agent_prompt_stalled after five seconds without observed activity. A timeout or server error is emitted as JSON on stderr with exit status 1. CLI usage errors exit with status 2.

Terminal window
herdsman integration install pi
herdsman integration install omp
herdsman integration install claude
herdsman integration install codex
herdsman integration install copilot
herdsman integration install devin
herdsman integration install droid
herdsman integration install kimi
herdsman integration install opencode
herdsman integration install kilo
herdsman integration install hermes
herdsman integration install qodercli
herdsman integration install qwen
herdsman integration install letta
herdsman integration install cursor
herdsman integration install mastracode
herdsman integration install grok
herdsman integration uninstall pi
herdsman integration uninstall omp
herdsman integration uninstall claude
herdsman integration uninstall codex
herdsman integration uninstall copilot
herdsman integration uninstall devin
herdsman integration uninstall droid
herdsman integration uninstall kimi
herdsman integration uninstall opencode
herdsman integration uninstall kilo
herdsman integration uninstall hermes
herdsman integration uninstall qodercli
herdsman integration uninstall qwen
herdsman integration uninstall letta
herdsman integration uninstall cursor
herdsman integration uninstall mastracode
herdsman integration uninstall grok
herdsman integration status [--outdated-only]

integration install claude, codex, and opencode also install Herdsman’s agent skill, integration uninstall removes it, and integration status lists it after the integrations.

Plugin commands install and run local executable workflow plugins. A plugin is a manifest plus out-of-process commands; Herdsman owns the host surface and plugins own their implementation language.

Install, list, and remove plugins:

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

plugin install accepts GitHub shorthand only, such as remziduzagac/herdsman-plugin-examples/worktree-bootstrap. It uses git, shows a trust preview in interactive terminals, runs supported manifest build commands, and stores GitHub installs in a Herdsman-managed directory. Use --yes for noninteractive installs. plugin update refreshes every GitHub-managed plugin when no targets are given, or only the listed plugin ids or GitHub sources. It preserves each install’s requested ref, skips unchanged commits and ignores locally linked plugins during bulk updates. Reinstalling a GitHub-managed plugin creates a new installation directory. Running plugins keep their original files; new invocations use the new installation. Installing over a locally linked plugin is refused. Plugin manifests must declare min_herdsman_version; install and link fail when the plugin requires a newer Herdsman binary. plugin list is human-readable by default; pass --json for the raw API response.

Plugin installation and enabled state are global to the current user. A plugin installed, linked, enabled, or disabled through one Herdsman session is immediately available with the same state in every session.

Local development:

Terminal window
herdsman plugin link <path> [--disabled]
herdsman plugin unlink <plugin_id>

plugin link accepts a plugin directory containing herdsman-plugin.toml or a direct manifest path. Use it while authoring or testing a plugin from a local checkout. plugin unlink and plugin uninstall unregister the plugin and leave files in place so running plugins can finish. Updates and reinstalls also retain previous installations; new invocations use the replacement without a config reload. A later successful installation/update or server startup removes obsolete managed installations after the servers using them have exited. Config reload does not release old installations. Plugins must stop detached background processes before their parent command or pane exits; processes surviving server exit are not protected from cleanup. Legacy installations without cleanup tracking and locally linked files are retained. For GitHub installs, uninstall accepts either the plugin id or the same owner/repo[/subdir...] shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.

Config directory:

Terminal window
herdsman plugin config-dir <plugin_id>

plugin config-dir prints the plugin’s config directory. It creates the directory if needed and seeds it from legacy plugin config locations when present. Use it in setup docs and shell scripts to point users at a stable path for .env files and other user-editable config, separate from the managed plugin checkout.

Actions:

Terminal window
herdsman plugin action list [--plugin ID]
herdsman plugin action invoke <action_id> [--plugin ID]

plugin action invoke starts the manifest command for an installed, enabled, platform-compatible plugin action and prints the started command log record in the JSON response. Use the qualified action id (plugin.id.action) when more than one plugin uses the same action id. Local action ids cannot contain dots, so qualified ids remain unambiguous even when plugin ids contain dots.

Logs:

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

Managed terminal panes:

Terminal window
herdsman 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]
herdsman plugin pane focus <pane_id>
herdsman plugin pane close <pane_id>

plugin pane open requires the plugin to be linked, enabled, and compatible with the current platform. It starts a manifest-declared [[panes]] command as a Herdsman-managed terminal pane. The manifest default is overlay, which opens a temporary zoomed overlay over the active pane. It can also open as a split, a new tab, a zoomed pane, or a session-modal popup that does not change the tab layout. --width and --height set the outer popup dimensions in terminal cells or percentages such as 80%; omitted dimensions default to half the terminal size, and values smaller than the popup minimum are clamped. A popup is not a Herdsman pane, does not export HERDSMAN_PANE_ID, and does not participate in pane or agent APIs. Native non-terminal plugin panes are outside plugin v1.

New panes identify as TERM_PROGRAM=herdsman, with TERM_PROGRAM_VERSION set to Herdsman’s version. They keep TERM=xterm-256color and COLORTERM=truecolor. They also get fish_handle_reflow=0, because Herdsman reflows text on resize; an inherited or explicit fish_handle_reflow value is kept. Herdsman removes inherited outer-terminal session markers (iTerm2, WezTerm, Kitty, Windows Terminal, tmux, screen, and Zellij), iTerm2’s LC_TERMINAL identity, and known Claude Code, Codex, and OMP session markers before applying explicit launch environment values. This prevents new panes from claiming the terminal or agent session that originally started the server. Ordinary environment variables, including API keys and display settings, remain inherited rather than being replaced with the attaching client’s environment. SSH-agent forwarding has its own reconnect handling. Existing pane processes are unchanged by this cleanup.

--env KEY=VALUE can be repeated on process-launching commands. It applies to the newly launched process only. Herdsman-managed variables such as HERDSMAN_SOCKET_PATH, HERDSMAN_BIN_PATH, HERDSMAN_ENV, HERDSMAN_WORKSPACE_ID, HERDSMAN_TAB_ID, HERDSMAN_PANE_ID, HERDSMAN_PLUGIN_ID, HERDSMAN_PLUGIN_ROOT, HERDSMAN_PLUGIN_CONFIG_DIR, HERDSMAN_PLUGIN_STATE_DIR, HERDSMAN_PLUGIN_ENTRYPOINT_ID, and HERDSMAN_PLUGIN_CONTEXT_JSON stay authoritative when they conflict with caller-provided env.

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.

These meanings apply to reads. For pane wait-output only, both recent and recent-unwrapped search the unwrapped recent snapshot; recent remains the default spelling.

Variable Purpose
HERDSMAN_CONFIG_PATH Override the config file path.
HERDSMAN_SESSION Select a named session for CLI commands.
HERDSMAN_SOCKET_PATH Low-level socket path override.
HERDSMAN_PROCESS_DETECTION Linux process detection strategy: native (default) or opt-in child-groups.
HERDSMAN_ENV Set to 1 inside Herdsman-managed pane processes.
HERDSMAN_PANE_ID Public pane id for the running pane process.
HERDSMAN_TAB_ID Public tab id for the running pane process.
HERDSMAN_WORKSPACE_ID Public workspace id for the running pane process.
HERDSMAN_LOG Set log filter, for example HERDSMAN_LOG=herdsman=debug.
HERDSMAN_DISABLE_SOUND Disable sound playback even when sound notifications are enabled.