CLI command reference
The @cubedot/cli drives the spec-first build loop from your repo. Requires Node.js ≥ 18. Install it with the pinned command from your project’s Integrations page.
Setup & health
Section titled “Setup & health”| Command | What it does |
|---|---|
cubedot init | Connect + scaffold the repo (--token, or --project / --key / --url; --enable-figma / --no-figma for the Figma MCP connection) |
cubedot sync | Refresh the local projection and detect drift |
cubedot status | Connectivity + file-health check (read-only) |
cubedot check | Validate markers/config (read-only, CI-friendly, meaningful exit code) |
cubedot update-agents | Re-copy the shipped agent prompt files into the repo |
cubedot uninstall | Remove everything init wrote and disconnect the repo |
cubedot migrate | One-time cutover for older repos: stops tracking .cubedot bookkeeping in git (refuses while un-pushed work is queued) |
Working the build loop
Section titled “Working the build loop”| Command | What it does |
|---|---|
cubedot work | List all unblocked functionalities, dependency-aware, not a strict sequence (aliases: next, todo) |
cubedot start <FN> | Set a functionality to in_progress |
cubedot complete <FN> | Set a functionality to code-complete |
cubedot done <FN> | Mark a functionality done (human gate; --discrepancy <text> to record open criteria, repeatable) |
cubedot reopen <FN> | Reopen a functionality that was marked done |
cubedot progress | Print the completion summary (read-only) |
cubedot screens | List every screen with its build status (read-only) |
cubedot push | Flush queued write-backs (transitions, reports, notes) to the project |
cubedot export | Dump pending work and local state for recovery; contains no secrets |
The status lifecycle
Section titled “The status lifecycle”A functionality moves todo → in_progress → code-complete → done. done is a human gate, it’s the point where you confirm the work actually meets its acceptance criteria, not just that code was written. Record any open criteria with --discrepancy.
Dev changes
Section titled “Dev changes”Off-spec work gets captured without polluting the spec. See Devchanges & write-back for the concepts.
| Command | What it does |
|---|---|
cubedot devchange capture [title] | Capture a dev change as already-done and push it, the default, atomic path |
cubedot devchange start <title> | Open a longer-running dev change |
cubedot devchange complete <code> | Mark it code-complete |
cubedot devchange done <code> | Close it (requires a report on disk) |
cubedot devchange list | List dev changes |
Deviations
Section titled “Deviations”| Command | What it does |
|---|---|
cubedot deviation list | List recorded deviations |
cubedot deviation resolve <id> | Mark a deviation resolved (--by <FN> to credit the fixing functionality) |
cubedot deviation defer <id> | Defer it |
cubedot deviation reopen <id> | Reopen it |
Verification (opt-in)
Section titled “Verification (opt-in)”Verification is a single switch, off by default. See Verification for how it works.
| Command | What it does |
|---|---|
cubedot config list / get / set <key> <value> | Read and set CLI configuration, including the verification switch |
cubedot verify-scope <FN> | Print what the verifier should check for a functionality |
cubedot ingest <FN> | Ingest a verification result |
cubedot tester-scope <FN> | Print the tester’s scope for a functionality |
cubedot report-scope <FN> | Produce a build report scope (used when verification is off; a report, never a verdict) |
cubedot conventions | Print the project’s verification conventions |
cubedot audit | Report-only audit of the local state (always exits 0) |
Troubleshooting
Section titled “Troubleshooting”See CLI troubleshooting for the common “Connecting…” and “command not found” fixes.