catalyst CLI reference
Every catalyst-* CLI is installed onto your PATH by
install-cli.sh (into
~/.catalyst/bin by default). This page lists all 30 of them — one line of
purpose plus the key subcommands — grouped by area. Run any tool with --help
for full syntax. The richer tools have their own reference pages (e.g.
catalyst-stack).
Daemons
Section titled “Daemons”catalyst-broker
Section titled “catalyst-broker”Manage the Catalyst event broker daemon (agent identity, ticket↔PR correlation, ticket_lifecycle routing).
Key subcommands: start, stop, restart, probe, status, logs, run
catalyst-execution-core
Section titled “catalyst-execution-core”Manage the execution-core composing daemon (Todo-state monitor + pull-loop scheduler + recovery contract).
Key subcommands: daemon, register, sessions, worktrees, branches, tidy, governance, beliefs, drain
catalyst-monitor
Section titled “catalyst-monitor”On-demand orch-monitor web-dashboard server management.
Key subcommands: start, stop, restart, status, open, url, forward-start, forward-stop, forward-status
catalyst-otel-forward
Section titled “catalyst-otel-forward”Entry wrapper for the otel-forward daemon (forwards OTel telemetry).
Key subcommands: (run catalyst-otel-forward --help)
Event & comms
Section titled “Event & comms”catalyst-events
Section titled “catalyst-events”Tail and wait-for primitives over the global append-only event log.
Key subcommands: (run catalyst-events --help)
catalyst-comms
Section titled “catalyst-comms”File-based JSONL agent communication channels (no HTTP, no server).
Key subcommands: join
catalyst-filter
Section titled “catalyst-filter”DEPRECATED alias for catalyst-broker (delegates so legacy callers keep working).
Key subcommands: start, stop, restart, probe, status, logs, run
catalyst-why
Section titled “catalyst-why”Explain why the daemon believes a worker is alive, stuck, or dead (belief→rule→facts trace).
Key subcommands: (run catalyst-why --help)
catalyst-transitions
Section titled “catalyst-transitions”Live, human-readable Linear-state + phase transition log (tails the event stream — bare runs forever).
Session & state
Section titled “Session & state”catalyst-session
Section titled “catalyst-session”Lifecycle CLI for Catalyst agent sessions (start/phase/metric/tool/pr → SQLite + event log).
Key subcommands: start, phase, metric, tool, iteration, pr, end, heartbeat, list, read
catalyst-state
Section titled “catalyst-state”Manage global orchestrator state at ~/catalyst/state.json (flock-protected RMW + event log).
Key subcommands: init, register, update, worker, heartbeat, attention, resolve-attention, event, archive, gc
boot-resume-approve
Section titled “boot-resume-approve”List boot-resume-gated tickets and approve one — writes the .boot-resume-approved sentinel so the daemon dispatches the gated phase without a restart (CTL-1443).
catalyst-db
Section titled “catalyst-db”SQLite-backed durable session store for agent runs (init/migrate, sessions, events, metrics).
Key subcommands: (run catalyst-db --help)
workflow-context
Section titled “workflow-context”Workflow context management utilities (recent docs, orchestration pointers, skill chaining).
Key subcommands: init, add, recent, most-recent, set-ticket, set-orchestration, ticket
Thoughts
Section titled “Thoughts”catalyst-thoughts
Section titled “catalyst-thoughts”Repair and verify the HumanLayer thoughts system for a Catalyst project.
Key subcommands: init-or-repair, when, directory, check
register-thought
Section titled “register-thought”PostToolUse Write hook that auto-registers thoughts/shared writes (reads hook JSON on stdin).
thoughts-pull-sync
Section titled “thoughts-pull-sync”Fast-forward every HumanLayer thoughts checkout so cross-host research reads fresh peer state.
Cluster & Linear
Section titled “Cluster & Linear”catalyst-cluster
Section titled “catalyst-cluster”Cluster administration — join tokens, roster, drain, concurrency tuning.
Key subcommands: (run catalyst-cluster --help)
catalyst-linear
Section titled “catalyst-linear”Replica-first Linear READ CLI — reads the local Catalyst-Cloud SQLite replica when opted in (CATALYST_LINEAR_REPLICA=on), else linearis; read-only (writes via linearis).
Key subcommands: (run catalyst-linear --help)
catalyst-linear-reconcile
Section titled “catalyst-linear-reconcile”Reconcile Linear ticket state from PR reality (merged→Done, open→In-Review); report or —write.
Key subcommands: (run catalyst-linear-reconcile --help)
HUD & display
Section titled “HUD & display”catalyst-statusline
Section titled “catalyst-statusline”Claude Code statusLine wrapper that also emits session.context events (reads JSON on stdin each tick).
catalyst-hud
Section titled “catalyst-hud”Ink TUI for the catalyst event stream (bare invocation starts the full-screen TUI).
catalyst-hud-classic
Section titled “catalyst-hud-classic”Color-coded terminal HUD for the event stream (minimal-deps fallback; bare runs forever).
Umbrella & lifecycle
Section titled “Umbrella & lifecycle”catalyst
Section titled “catalyst”The single front-door router for the Catalyst toolchain (git-style dispatch to every catalyst-* tool).
Key subcommands: (run catalyst --help)
catalyst-stack
Section titled “catalyst-stack”Bring the Catalyst service stack up or down on this host (idempotent, dependency-ordered).
Key subcommands: (run catalyst-stack --help)
catalyst-install
Section titled “catalyst-install”Provision or tear down this node for its class (composes setup scripts; install/uninstall/reinstall).
Key subcommands: (run catalyst-install --help)
catalyst-doctor
Section titled “catalyst-doctor”Fail-closed activation gate — class-aware health/activation grade (exit 0 ⇒ safe to activate).
Key subcommands: (run catalyst-doctor --help)
catalyst-backup
Section titled “catalyst-backup”Capture / restore a node’s restorable identity + state bundle (bare backup writes a secrets bundle).
catalyst-claude
Section titled “catalyst-claude”Wrapper that registers a Catalyst session around claude, then execs the interactive claude process.
emit-lifecycle-event
Section titled “emit-lifecycle-event”Claude Code Stop/SubagentStop hook — fallback agent.checkout emitter for the broker.