CLI Reference — Registered Commands and Options

Verified against source commit 34fdcb80543903b054a982cc48bb302ae6871682. The inventory below comes from the actual Commander tree returned by createProgram(), not a grep of command strings or an installed CLI from a different commit.

There are 90 top-level registrations, 410 registered command objects below rig (including groups and the hidden restore apply command), and 1,304 explicitly registered option objects, including the root version option. Aliases do not add command objects; short/long spellings of one option do not add option objects. Commander-generated help is additional. These are counts for that source snapshot, not a claim about a deployed release. The provider-switch and set-runtime rows include the later account-home options; those additions are not included in the snapshot counts. The environment section and the host edit, host remove and terminal attach rows were added later from source at 522d635c, and aren't in the snapshot counts either. With environment, main registers 91 top-level commands.

Reading this reference

Each table row lists one registered command, its positional arguments, command aliases, and its own declared options. <value> denotes a required positional/option value; [value] is optional; ... is variadic. An option marked required was registered with Commander's mandatory option setting. An option marked (repeatable) collects every value when it is given more than once. Conditional requirements enforced by an action are not encoded by this inventory.

Use rig <command> --help for descriptions, choices, defaults, and examples. Defaults may depend on the current directory, configuration, or action code; they are not fixed by the flags table. Parent command options are listed on the parent row, not repeated on every child. The root declares -V, --version; Commander also provides -h, --help and applicable help [command] handling. The only explicit command alias at this pin is rig host ls for host list.

An option named --json selects the command's JSON mode; it does not imply that every verb shares one response schema. The handler and its daemon route remain the source for result/error shape and side effects.

Entry points and practical routes

Bare rig opens the TUI, the status dashboard rather than an agent conversation, when both stdin and stdout are terminals. Arguments, pipes, and redirected streams follow normal CLI parsing. runFrontDoor and openMissionControl own the entry behavior; tuiCommand owns explicit TUI options; rig terminal open saved:kernel --window opens a terminal view of the OpenRig TUI, the operator and the advisor (in a new tab or window, or the current Herdr session), and rig tui --shared is the dashboard-only fallback when that view cannot open. A daemon-down transport result can still open the recovery cockpit; it is not automatically a reason to exit before rendering.

Do not confuse rig project's coordination/classification surface with rig scope's project and work-tree commands. Likewise, rig spec manages rig specifications, rig specs browses the spec library, and rig workflow specs lists workflow specifications. The tree below preserves those distinct registrations.

A successful read, queue admission, terminal delivery, proof judgment, and publication are different operations. Consult the relevant command handler and workflow runtime when deciding what a result establishes. This reference does not turn an inventory entry into permission to perform that operation.

Reproducing the registration inventory

In a development checkout at the stamped commit, after installing its locked dependencies and building the daemon and CLI, this import walks the registered tree without parsing arguments or invoking command actions:

node --input-type=module <<'JS'
import { createProgram } from './packages/cli/dist/index.js';
const root = createProgram();
const rows = [];
function walk(command, prefix = '') {
  const path = prefix ? `${prefix} ${command.name()}` : command.name();
  rows.push({
    path,
    aliases: command.aliases(),
    arguments: command.registeredArguments.map(a => ({
      name: a.name(), required: a.required, variadic: a.variadic,
    })),
    options: command.options.map(o => ({
      flags: o.flags, required: Boolean(o.mandatory),
    })),
  });
  for (const child of command.commands) walk(child, path);
}
walk(root);
console.log(JSON.stringify({
  topLevel: root.commands.length,
  registeredCommands: rows.length - 1,
  declaredOptions: rows.reduce((n, row) => n + row.options.length, 0),
  rows,
}, null, 2));
JS

This inspects registration, not action semantics or availability of a running daemon. index.ts imports the command factories; their implementations live in packages/cli/src/commands/. The tables below retain registration order. Only the command/argument/alias/ option cells are mechanically transcribed; the explanations above are authored.

Registered command tree

Root: rig; declared option: -V, --version.

start

daemon

status

rig status --json prints one object: daemon, kernel, workspaceRoot, rigs and cmux. daemon.reachable has three values. true: the daemon answered its health probe (it may still report healthy: false, and may carry a reason and eventLoop evidence). false: positively down (state is stopped or stale). null: not confirmed (state is unverified, or running with reason: "unresponsive" because /healthz did not answer). When reachable is not true, the sections that were not read are null.

snapshot

restore

crash-cart

gateway

• Several people may be registered. Organizations, groups, readable policy, shared channels and the default person are kept in $OPENRIG_HOME/gateway/participants.yaml, never in a person's fragment, so an older daemon still loads every person after a rollback. human set <entityId> organization|groups|policy <value> writes there (unset clears; @<path> reads a policy file). participants --json carries each participant's kind, address, organization, groups, default and policy (a list of { source, text }, organization first), plus default, organizations, groups, warnings and participantFile. default with no argument prints the current default and its source (chosen or only-person), or null with the reason. See docs/reference/gateway-participants.md.
• human set <entityId> slack-subscription <value> — sets the person's Slack subscription: every-ask (the default) posts every ask to them to Slack; urgent-only posts only asks created with --alert, and other asks wait on Steering and the TUI; unset removes the authored subscription so the default applies. human show prints the value with its origin, authored or default (slack-subscription: every-ask (default)); --json carries it as record.slackSubscription { value, source }.

parked

export

import

ui

tui

package

bootstrap

requirements

discover

attach

bind

adopt

bundle

up

down

archive

unarchive

host

rig host pair needs the target daemon to run with OPENRIG_AUTH_BEARER_TOKEN set, even when it is bound to a tailnet address and so starts without one: pairing hands over that token. Without it, the target's POST /api/hosts/pair-request answers 409 pair_target_no_bearer; it answers 409 pair_human_required when no single registered person can approve (none, or several with no default; name one with --human) (packages/daemon/src/routes/hosts.ts:167-186).

Registration makes a host visible in topology; remote FEED attention remains opt-in. The human-readable success output of host add and host pair now includes the FEED next step alongside the existing host doctor suggestion. For an HTTP entry named laptop, run this on the local instance to include its attention items:

rig config set feed.subscriptions.laptop.enabled true

The key uses the registry id, including any dots, and defaults to false. Registration does not change that setting. SSH entries instead explain that FEED needs an HTTP entry; ids reserved by feed settings (such as progress) get a different-id suggestion rather than an invalid command. --json keeps its single JSON result without these hints. The host CLI tests execute the advertised command against an isolated config and cover registration, reserved names and JSON output; pairing responses are simulated, so they do not establish connectivity to a live peer.

ps

• --nodes --json — each seat carries the daemon's served needsAttention flag; the CLI doesn't re-derive it, and it is absent when an older daemon doesn't serve it. arbitratedNeedsInput and needsInputEvidence ({ rung, observedAt } or null) come with --full, or by name through --fields. startedWithoutRequired lists the required startup files a handover's successor started without, and the compact read keeps it.

roster

mcp

acp

exec

agent

spec

transcript

send

stream

Stream intake: the stream.intake setting (default queue.worker, or a canonical <seat>@<rig>) receives each emitted item. It opens an intake row for that seat, which wakes it, or adds a note to that seat's intake row still pending; a critical or interrupting item makes the row urgent. rig config set stream.intake off keeps emits passive. A runner's default-permit record (tag runner-permission-permit) opens no row.

queue

slack

project

view

terminal

See named terminal sessions to select a Herdr session per request, including session-bound previews and window reuse.

watchdog

workflow

capture

broadcast

walk

ask

Wake seat targets must include the rig: member@rig or member@rig@N (1 = newest tenure). Values without @ go unchanged to the runtime as a session ID or title; a bare member name is not resolved within <rig>. Only Claude and Codex tenures can be woken.

chatroom

specs

context

plugin

skill

agent-image

community-harness

environment

It drives the maintained OpenShell reference; see the OpenShell example.

fork

workspace

mode

policy

whoami

config

• init-workspace — rig config init-workspace creates missing missions/, exhaust/, SPEC.md, project.yaml, workspace.yaml, and .gitignore entries at the configured workspace root (or --root <path>). Initialization is additive and preserves existing files; a complete six-entry scaffold is a no-op. --force is deprecated compatibility and still preserves existing files. --dry-run reports planned additions without writing; incompatible path types are reported before any writes.

file

preflight

auth

provider

usage

telemetry

health

doctor

expand

add

create

grow

edge

add requires from, to and --kind, and is idempotent: a repeat reports the existing edge and writes nothing. remove deletes the edge with that ID; a repeat changes nothing and returns edge_not_found (exit 1). See changing edges on an existing rig for input and receipt examples, rollback, and snapshot behavior.

reconcile-session

env

unclaim

release

launch

remove

shrink

destroy

setup

restore-check

restore-packet

compact-plan

• --threshold-tokens and --threshold-percent set the plan's own candidate thresholds (the percentage applies when a seat's context window size is missing). They are not the automatic compaction setting: the output labels them as the plan's own and shows policies.claude_compaction (enabled, threshold_percent) separately, for comparison only, or says it couldn't be read.

compact

heartbeat

seat

A rig seat stop that successfully kills the current session records that it was intentionally stopped. With other healthy members running, the rig's lifecycleState in rig ps and the TUI stays running; the stopped member no longer makes it degraded. Stopping every member leaves the rig stopped. Node JSON exposes intentionallyStopped in compact, --full, and --fields output.

Process counts still reflect reality: stopping one of two members leaves nodeCount: 2, runningCount: 1, and process status: partial. Node lifecycle, resume information, and attention diagnostics remain available. A crash or attention condition on another member still affects the rig lifecycle.

Stop intent survives daemon restarts and audit retention. It applies only to the latest exited session while the seat has no binding; a subsequent session status change clears it, and a new session starts without it. Existing exits are not backfilled as intentional stops. If the session disappears between the live probe and the stop, its unexplained exit still affects rig health. The internal stop in rig seat launch --fresh --stop does not record final stop intent, so a refused replacement still degrades a rig with other healthy members running.

rig start --last and rig start --rigs <rig> use the full per-seat lifecycle for restore selection. A partly running rig with an intentionally stopped member still appears as a degraded candidate and reports rig_not_stopped (exit 1) when restore is attempted. Launch scheduling and restore eligibility remain unchanged.

See per-seat terminal delivery for off, draft-aware and hold modes, immediate refusal results and held-message inspection.

handover

startup-proof

scope

proof