CLI reference

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
herdr --no-session            # single-process escape hatch
herdr --default-config        # print default config
herdr update                  # download and install the latest version
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 runs the headless server explicitly. Use it for supervised or service-style setups. reload-config applies reloadable settings without restarting panes.

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

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 rename <pane_id> <label>|--clear
herdr pane split <pane_id> --direction right|down [--cwd PATH] [--focus] [--no-focus]
herdr pane close <pane_id>

Read output:

herdr pane read <pane_id> [--source visible|recent|recent-unwrapped] [--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]

Agents

herdr agent list
herdr agent get <target>
herdr agent read <target> [--source visible|recent|recent-unwrapped] [--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...>

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.

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 claude
herdr integration install codex
herdr integration install opencode
herdr integration install hermes
herdr integration uninstall pi
herdr integration uninstall claude
herdr integration uninstall codex
herdr integration uninstall opencode
herdr integration uninstall hermes
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.

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.