Commands Cheat Sheet

Fresh

Condensed from the CLI Reference. Most commands print JSON.

Launch and status

Command	Does
`herdr`	Launch or attach to the default session
`herdr --session work`	Launch or attach to a named session
`herdr --remote workbox`	Attach through SSH with local keybindings
`herdr --remote workbox --remote-keybindings server`	Use the remote server's keybindings
`herdr --remote workbox --handoff`	Opt into experimental live handoff
`herdr --no-session`	Single-process escape hatch
`herdr --default-config`	Print the default config
`herdr --version`	Print version
`herdr status` / `status server` / `status client`	Status info

Update and channels

Command	Does
`herdr update`	Install from the configured channel
`herdr update --handoff`	Live handoff for supported running servers
`herdr channel show`	Print `stable` or `preview`
`herdr channel set preview` / `set stable`	Switch channels (direct installs only)

Server

Command	Does
`herdr server`	Run the headless server explicitly
`herdr server stop`	Stop the default server (exits pane processes)
`herdr server reload-config`	Apply reloadable settings without restarting panes
`herdr server agent-manifests [--json]`	Show active detection manifest sources
`herdr server update-agent-manifests [--json]`	Fetch + reload remote manifests now
`herdr server reload-agent-manifests`	Reload after local override edits

Sessions

Command	Does
`herdr session list [--json]`	List sessions
`herdr session attach <name>`	Attach (creates if needed)
`herdr session stop <name> [--json]`	Stop a session's server
`herdr session delete <name> [--json]`	Delete a session

Use default as the name to stop the default session explicitly.

Workspaces and worktrees

Command	Does
`herdr workspace list / get / focus / rename / close`	Workspace CRUD
`herdr workspace create [--cwd PATH] [--label TEXT] [--no-focus]`	New workspace
`herdr worktree list [--workspace ID \| --cwd PATH]`	List Git worktree checkouts
`herdr worktree create [--branch NAME] [--base REF] [--path PATH]`	Create checkout + workspace
`herdr worktree open (--path PATH \| --branch NAME)`	Open existing checkout
`herdr worktree remove --workspace ID [--force]`	`git worktree remove` (never deletes the branch)

Tabs

Command	Does
`herdr tab list / get / focus / rename / close`	Tab CRUD
`herdr tab create [--workspace ID] [--cwd PATH] [--label TEXT]`	New tab

Panes

Command	Does
`herdr pane list / get / rename / close`	Pane CRUD
`herdr pane split <id> --direction right\|down [--ratio FLOAT] [--cwd PATH]`	Split
`herdr pane layout / neighbor / edges [--current]`	Layout inspection
`herdr pane focus --direction left\|right\|up\|down`	Directional focus
`herdr pane resize --direction DIR [--amount FLOAT]`	Resize
`herdr pane zoom [--toggle\|--on\|--off]`	Zoom
`herdr pane swap --direction DIR` or `--source-pane ID --target-pane ID`	Swap (same tab only)
`herdr pane read <id> [--source visible\|recent\|recent-unwrapped\|detection] [--lines N] [--ansi]`	Read output
`herdr pane send-text <id> <text>`	Literal text
`herdr pane send-keys <id> <key> ...`	Key presses
`herdr pane run <id> <command>`	Text + Enter atomically (prefer this)
`herdr pane report-agent <id> --source ID --agent LABEL --state STATE`	Report agent state from hooks
`herdr pane report-metadata <id> --source ID [--title ...] [--display-agent ...]`	Display-only metadata

Agents

Command	Does
`herdr agent list / get <target>`	Inspect agents
`herdr agent read <target> [--source ...] [--lines N]`	Read agent terminal
`herdr agent send <target> <text>`	Send text
`herdr agent rename <target> <name>\|--clear`	Name an agent target
`herdr agent focus <target>`	Focus its pane
`herdr agent wait <target> --status idle\|working\|blocked\|unknown [--timeout MS]`	Wait for state
`herdr agent attach <target> [--takeover]`	Direct attach to one agent
`herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right\|down] -- <argv...>`	Spawn an agent
`herdr agent explain <target> [--json\|--verbose]`	Why is the state what it is

Targets accept terminal IDs, unique agent names, detected/reported labels, and legacy pane IDs.

Waits

Command	Does
`herdr wait output <pane_id> --match <text> [--regex] [--timeout MS]`	Wait for pane output
`herdr wait agent-status <pane_id> --status done [--timeout MS]`	Wait for agent state

Integrations

Command	Does
`herdr integration install <agent>`	pi, omp, claude, codex, copilot, droid, kimi, opencode, kilo, hermes, qodercli, cursor
`herdr integration uninstall <agent>`	Remove Herdr's entries only
`herdr integration status [--outdated-only]`	Installed versions

Notifications

Command	Does
`herdr notification show <title> [--body TEXT] [--position POS] [--sound none\|done\|request]`	Show a toast via configured delivery

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`	Log filtering, e.g. `HERDR_LOG=herdr=debug`
`HERDR_DISABLE_SOUND`	Disable sound playback
`HERDR_REMOTE_BINARY`	Local binary path for remote attach
`HERDR_ENV`	Set to `1` inside Herdr-managed panes (agent skill guard)