CLI reference

This page lists every flockr command and its options, taken from flockr --help and flockr <command> --help. The installed binary is the authority: run those commands to see the help for your version.

Most control commands print JSON. Server errors are JSON on stderr with exit status 1. Syntax errors exit with status 2.

Global usage and options

flockr [options]
flockr --session <name> [options]
flockr --machine <label-or-id> <command>
flockr --remote <ssh-target> [--session <name>]

Option	What it does
(none)	Launch or attach to the persistent session.
`--session <name>`	Use or create a named persistent session.
`--machine <label-or-id>`	Run an API command on a saved SSH machine. See Remote machines.
`--remote <target>`	Attach through SSH to a remote flockr server. See Remote machines.
`--remote-keybindings <local\|server>`	Keybindings for `--remote` app attach (default: `local`).
`--handoff`	Opt into live handoff for update or remote attach.
`--default-config`	Print the default configuration and exit.
`--skill`	Print the agent skill file and exit.
`--version`, `-V`	Print the version and exit.
`--help`, `-h`	Show help, including the config path, log paths, and environment.

Run a command group without a subcommand to print its help, for example flockr pane. Don't run bare flockr to explore: it launches or attaches the UI.

IDs and targets

Space (workspace) IDs look like w1, tab IDs like w1:t1, and pane IDs like w1:p1.
--current targets the pane the command runs in (from FLOCKR_PANE_ID).
Agent commands take a <TARGET>: a unique live agent name, or the pane ID hosting the agent.
--focus and --no-focus choose whether a new space, tab, or pane takes focus.

session

Manage named persistent sessions.

Command	Arguments and options	What it does
`session list`	`--json`	List sessions.
`session attach`	`<NAME>`	Attach to a session.
`session stop`	`<NAME>`, `--json`	Stop a session.
`session delete`	`<NAME>`, `--json`	Delete a stopped session.

workspace

Manage workspaces (spaces) over the socket API.

Command	Arguments and options	What it does
`workspace list`		List workspaces.
`workspace create`	`--cwd <PATH>`, `--label <TEXT>`, `--env <KEY=VALUE>` (set an environment variable for the launched process), `--focus`, `--no-focus`	Create a workspace.
`workspace get`	`<workspace_id>`	Show a workspace.
`workspace focus`	`<workspace_id>`	Focus a workspace.
`workspace rename`	`<WORKSPACE_ID> <LABEL>...`	Rename a workspace.
`workspace report-metadata`	`<WORKSPACE_ID>`, `--source <ID>` (required), `--token <NAME=VALUE>`, `--clear-token <NAME>`, `--seq <N>`, `--ttl-ms <N>`	Report display-only workspace metadata, such as values for custom sidebar tokens.
`workspace close`	`<workspace_id>`	Close a workspace.

worktree

Manage Git worktree-backed workspaces. Every subcommand takes --trust-repository, which grants Git trust for that request; use it only for a repository you have checked.

Command	Arguments and options	What it does
`worktree list`	`--workspace <ID>`, `--cwd <PATH>`	List worktree workspaces.
`worktree create`	`--workspace <ID>`, `--cwd <PATH>`, `--branch <NAME>`, `--base <REF>`, `--path <PATH>`, `--label <TEXT>`, `--focus`, `--no-focus`	Create and open a Git worktree.
`worktree open`	`--path <PATH>` or `--branch <NAME>` (one required), `--workspace <ID>`, `--cwd <PATH>`, `--label <TEXT>`, `--focus`, `--no-focus`	Open an existing Git worktree.
`worktree remove`	`--workspace <ID>` (required), `--force`	Remove a worktree checkout.

tab

Manage tabs over the socket API.

Command	Arguments and options	What it does
`tab list`	`--workspace <WORKSPACE_ID>`	List tabs.
`tab create`	`--workspace <WORKSPACE_ID>`, `--cwd <PATH>`, `--label <TEXT>`, `--env <KEY=VALUE>`, `--focus`, `--no-focus`	Create a tab.
`tab get`	`<TAB_ID>`	Show a tab.
`tab focus`	`<TAB_ID>`	Focus a tab.
`tab rename`	`<TAB_ID> <LABEL>...`	Rename a tab.
`tab close`	`<TAB_ID>`	Close a tab.

pane

Control terminal panes. Commands that take --pane <ID> also take --current for the calling pane. Directions are left, right, up, and down unless noted.

Command	Arguments and options	What it does
`pane list`	`--workspace <WORKSPACE_ID>`	List panes.
`pane current`	`--pane <ID>`, `--current`	Show the current pane.
`pane get`	`<PANE_ID>`	Show a pane.
`pane layout`	`--pane <ID>`, `--current`	Show pane layout information.
`pane process-info`	`--pane <ID>`, `--current`	Show pane process information.
`pane neighbor`	`--direction <DIRECTION>` (required), `--pane`, `--current`	Find a pane neighbor.
`pane edges`	`--pane <ID>`, `--current`	Show pane edge information.
`pane focus`	`--direction <DIRECTION>` (required), `--pane`, `--current`	Focus a neighboring pane.
`pane resize`	`--direction <DIRECTION>` (required), `--amount <FLOAT>`, `--pane`, `--current`	Resize a pane split.
`pane zoom`	`[PANE_ID]`, `--pane`, `--current`, `--toggle`, `--on`, `--off`	Toggle or set pane zoom.
`pane read`	`<PANE_ID>`, `--source <visible\|recent\|recent-unwrapped\|detection>`, `--lines <N>`, `--format <text\|ansi>`, `--ansi`, `--raw`	Read pane terminal output.
`pane rename`	`<PANE_ID> [LABEL]...`, `--clear`	Rename a pane.
`pane input`	`<PANE_ID>` or `--pane`/`--current`, `--right-click <flockr\|pane>` (required)	Set pane input routing.
`pane split`	`[PANE_ID]`, `--direction <right\|down>` (required), `--pane`, `--current`, `--ratio <FLOAT>`, `--cwd <PATH>`, `--focus`, `--no-focus`, `--right-click <flockr\|pane>`, `--env <KEY=VALUE>`	Split a pane. The new pane is in `.result.pane`.
`pane swap`	`--pane`, `--current`, `--direction <DIRECTION>`, `--source-pane <ID>`, `--target-pane <ID>`	Swap panes.
`pane move`	`<PANE_ID>`, one of `--tab <TAB_ID>`, `--new-tab`, or `--new-workspace`; `--split <right\|down>`, `--target-pane <ID>`, `--ratio <FLOAT>`, `--workspace <ID>`, `--label <TEXT>`, `--tab-label <TEXT>`, `--focus`, `--no-focus`	Move a pane.
`pane close`	`<PANE_ID>`	Close a pane.
`pane send-text`	`<PANE_ID> <TEXT>...`	Send literal text to a pane.
`pane send-keys`	`<PANE_ID> <KEY>...`	Send key presses. Use `esc` for Escape (`escape` also works).
`pane wait-output`	`<PANE_ID>`, `--source <visible\|recent\|recent-unwrapped>`, `--lines <N>`, `--match <TEXT>`, `--regex <PATTERN>`, `--timeout <MS>`, `--raw`	Wait for matching output. Existing output can match. Without `--timeout` it waits indefinitely.
`pane run`	`<PANE_ID> <COMMAND>...`	Send the command text and Enter in one call.
`pane report-agent`	`<PANE_ID>`, `--source <ID>`, `--agent <LABEL>`, `--state <idle\|working\|blocked\|unknown>` (all required), `--message <TEXT>`, `--seq <N>`, `--agent-session-id <ID>`, `--agent-session-path <PATH>`, `-- [RESUME_ARG]...`	Report pane agent lifecycle state. The resume command after `--` resumes the session after a restart.
`pane report-agent-session`	`<PANE_ID>`, `--source <ID>`, `--agent <LABEL>` (required), `--seq <N>`, `--agent-session-id <ID>`, `--agent-session-path <PATH>`, `--session-start-source <SOURCE>`, `-- [RESUME_ARG]...`	Report pane agent session identity.
`pane release-agent`	`<PANE_ID>`, `--source <ID>`, `--agent <LABEL>` (required), `--seq <N>`	Release pane agent lifecycle authority.
`pane report-metadata`	`<PANE_ID>`, `--source <ID>` (required), `--agent <LABEL>`, `--applies-to-source <ID>`, `--title <TEXT>`, `--display-agent <TEXT>`, `--state-label <STATUS=TEXT>`, `--token <NAME=VALUE>`, `--clear-token <NAME>`, `--clear-title`, `--clear-display-agent`, `--clear-state-labels`, `--seq <N>`, `--ttl-ms <N>`	Report display-only pane metadata.

Read sources: visible is the rendered viewport; recent is recent output with soft wraps; recent-unwrapped joins soft wraps (best for logs); detection is the plain-text snapshot flockr uses for agent detection.

agent

Control and inspect agent panes. States for --until are idle, working, blocked, done, and unknown.

Command	Arguments and options	What it does
`agent list`		List agents.
`agent get`	`<TARGET>`	Show an agent.
`agent focus`	`<TARGET>`	Focus an agent.
`agent read`	`<TARGET>`, `--source <visible\|recent\|recent-unwrapped\|detection>`, `--lines <N>`, `--format <text\|ansi>`, `--ansi`	Read agent terminal output.
`agent send-keys`	`<TARGET> <KEY>...`	Send key presses to an agent.
`agent rename`	`<TARGET> <NAME>` or `--clear`	Rename an agent.
`agent wait`	`<TARGET>`, `--until <STATUS>` (repeatable), `--timeout <MS>`	Wait until an agent reaches a state. Without `--until` it matches `idle`, `done`, or `blocked`. Without `--timeout` it waits indefinitely.
`agent prompt`	`<TARGET> <TEXT>`, `--wait`, `--until <STATUS>` (repeatable), `--timeout <MS>`	Submit a prompt. Rejected with `agent_blocked` if the agent is blocked. With `--wait`, returns `agent_prompt_stalled` if no working or blocked state shows within 5000 ms.
`agent start`	`<NAME>`, `--kind <KIND>`, `--pane <ID>` (required), `--timeout <MS>` (default 30000, max 300000), `-- [AGENT_ARG]...`	Start a supported agent in an existing pane at its shell prompt. See Integrations for the kinds.
`agent attach`	`<TARGET>`, `--takeover`	Attach directly to an agent terminal.
`agent explain`	`<TARGET>` or `--file <PATH>`, `--agent <LABEL>`, `--json`, `--format <text\|json>`, `-v`/`--verbose`	Explain agent detection state.

terminal

Attach to or observe raw terminal streams.

Command	Arguments and options	What it does
`terminal attach`	`<TERMINAL_ID>`, `--takeover`	Attach directly to a terminal stream.
`terminal session control`	`<TARGET>`, `--takeover`, `--cols <N>`, `--rows <N>`	Control a terminal stream.
`terminal session observe`	`<TARGET>`, `--cols <N>`, `--rows <N>`	Observe a terminal stream.
`terminal title set`	`<TITLE>`	Set the outer terminal title.
`terminal title clear`		Clear the outer terminal title.

notification

Command	Arguments and options	What it does
`notification show`	`<TITLE>`, `--body <TEXT>`, `--position <top-left\|top-right\|bottom-left\|bottom-right>`, `--sound <none\|done\|request>`	Show a notification.

integration

Manage built-in agent integrations. See Integrations.

Command	Arguments and options	What it does
`integration install`	`<TARGET>`	Install an integration.
`integration uninstall`	`<TARGET>`	Uninstall an integration.
`integration status`	`--outdated-only`	Show integration status.

Targets: pi, omp, claude, codex, copilot, devin, droid, kimi, opencode, kilo, hermes, qodercli, qwen, cursor, mastracode, antigravity-cli, grok, and letta.

config

Command	Arguments and options	What it does
`config check`		Validate `config.toml` and print diagnostics.
`config reset-keys`		Back up `config.toml` and remove custom keybindings.

update and channel

Command	Arguments and options	What it does
`update`	`--handoff` (try live handoff after installing)	Listed as "download and install the latest version". In flockr it stops with "flockr does not self-update". See Updating.
`channel show`		Print the configured update channel.
`channel set`	`<stable\|preview>`	Choose the update channel.

server

Run or control the headless server. flockr server with no subcommand runs as a headless server.

Command	Arguments and options	What it does
`server stop`		Stop the running server via the API socket. This stops its pane processes too.
`server reload-config`		Reload `config.toml` in the running server.
`server agent-manifests`	`--json`	Show active agent detection manifests.
`server update-agent-manifests`	`--json`	Fetch and reload agent detection manifests. Disabled in flockr.
`server reload-agent-manifests`		Reload local agent detection manifest overrides.

api

Inspect socket API metadata and live runtime state. See Socket API.

Command	Arguments and options	What it does
`api snapshot`		Print the live session snapshot.
`api schema`	`--json`, `--output <PATH>`	Print or write the bundled API schema.

status

Command	Arguments and options	What it does
`status`	`--json`	Show local client and running server status.
`status server`	`--json`	Show running server status.
`status client`	`--json`	Show local client status.

completion

flockr completion <SHELL>

Generate a shell completion script. <SHELL> is bash, elvish, fish, powershell, or zsh.

plugin

Install and run workflow plugins. Plugins written for herdr work unchanged; see flockr and herdr.

Command	What it does
`plugin install`	Install a plugin from GitHub.
`plugin uninstall`	Uninstall a plugin.
`plugin update`	Update GitHub-installed plugins.
`plugin link`, `plugin unlink`	Link or unlink a local plugin.
`plugin enable`, `plugin disable`	Enable or disable a plugin.
`plugin list`	List installed plugins.
`plugin config-dir`	Print a plugin config directory.
`plugin action`	List or invoke plugin actions.
`plugin log` (alias `logs`)	Inspect plugin command logs.
`plugin pane`	Manage plugin-owned panes.

machine, flock, message, and mobile

These groups are covered on their own pages.

Group	Subcommands	Docs
`machine`	`list`, `status`, `reconnect`, `add`, `rename`, `remove`, `enable`, `disable`	Remote machines
`flock` (1.2.0)	`init`, `invite`, `join`, `members`, `agents`, `status`, `remove`	Flock setup
`message` (1.2.0)	`send`, `reply`, `read`, `log`, `pending`, `approve`, `deny`, `cancel`	Agent messages
`mobile` (1.2.0)	`pair`, `devices`, `status`	Pairing a phone