Skip to content

cambium CLI

cambium is published as @oakgreencc/cambium. It needs Node ≥ 22.13 (node:sqlite) and graft on PATH.

Every command takes --config <file>. Default: $CAMBIUM_CONFIG, then ~/.cambium/config.json.

Command Behaviour
cambium start [--once] Foreground daemon, one tick every tickSeconds. --once runs a single tick. SIGTERM/SIGINT stop it after the current tick; workers keep running and are re-adopted on restart. One daemon per database.
cambium status [--json] Mode, last tick, queue counts, workers, failed steps. Exit 1 when there is no heartbeat or it is older than 3 ticks. --json returns { "mode", "heartbeat" }, also while the daemon is down.
cambium pause Read and heartbeat only: no transitions, no starts. Running workers are left alone.
cambium drain Reconcile, watch and sweep as usual; start nothing new.
cambium resume Back to running.

The mode is stored in the SQLite database (paths.db, table control).

Command Engine Behaviour
cambium run task --issue <n> [--repo <o/n>] legacy Claim one open q:task issue, run its worker in the foreground, then make the transition the daemon would.
cambium run task --issue <n> [--repo <o/n>] [--follow] graph Advance one issue through the task graph. A q:task issue without a lease starts with a foreground worker; anything else resumes where its marker rests.
cambium run pr --issue <n> [--repo <o/n>] [--follow] graph One turn of the PR graph for the issue’s PR.
cambium run dispatch --issue <n> [--repo <o/n>] [--follow] graph Triage one q:intake issue with a foreground triage worker (the dispatch cap does not apply), then end the dispatch graph. A tracked triage worker resumes at triaging.
cambium run release-prepare [--repo <o/n>] graph Run release-prepare now, whatever release.time: cut a release branch and open its PR. Counts as the day’s run.
cambium run release-promote [--repo <o/n>] [--issue <pr>] graph A release-promote turn for each q:promote promotion PR, or only <pr>. PRs not ready are reported.
cambium run rescue [--repo <o/n>] [--issue <n>] graph Without --issue: list items the rescue sweep would find stuck now, with symptoms; changes nothing. With it: rescue that item with a foreground worker and carry out its verdict.

run task, run pr and run dispatch stop at the first wait that is not ready. --follow re-reads and polls every tickSeconds until the graph ends (for run pr, until the issue is closed).

Command Behaviour
cambium gc [--dry-run] [--repo <o/n>] Collect worktrees now. --dry-run only reports. See worktree GC.
cambium install [--dry-run] Write the launchd agent ~/Library/LaunchAgents/com.oakgreencc.cambium.plist (KeepAlive, RunAtLoad) for start --config <this config>. --dry-run prints it. Does not call launchctl; prints the command.
cambium update [--check] [--version <v>] Install the latest version (or <v>, older included) from npm into this global install, then SIGTERM the launchd agent so KeepAlive starts the new version. --check only reports. No config file needed.

cambium update and update.auto act only on a global npm install (<prefix>/lib/node_modules/@oakgreencc/cambium), into the same prefix. A source checkout, npm link or a copy inside another package’s node_modules is left alone. npm is the one next to the running Node, else npm on PATH. The version is the registry’s latest dist-tag.

  • When the agent is not loaded, cambium update only installs.
  • update.auto applies only when the process is the launchd agent (XPC_SERVICE_NAME=com.oakgreencc.cambium). A failed check or install is a warning, retried at the next check. The last check time is update.lastCheck in the control table.
  • The plist is never rewritten by an update.
Path Contents
<paths.logs>/cambium.log Daemon log; one .1 kept
<paths.logs>/cambium.launchd.err.log launchd’s stderr
paths.heartbeat Heartbeat
paths.db SQLite: tracked workers, mode, clocks