CLI reference

Fresh

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

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:

herdr status

herdr status server

herdr status client

Server

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

herdr 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 Herdr toasts. --sound defaults to none; done and request play the existing finished and needs-attention sounds only when the notification is shown.

Sessions

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

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:

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

Worktrees

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

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

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:

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:

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:

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:

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

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

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:

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

Wait for pane agent state:

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

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.