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.
Daemon and mode
Section titled “Daemon and mode”| 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).
Foreground runs
Section titled “Foreground runs”| 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).
Maintenance
Section titled “Maintenance”| 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. |
Self-update
Section titled “Self-update”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 updateonly installs. update.autoapplies 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 isupdate.lastCheckin thecontroltable.- 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 |