@intutic/cli 2.8.0 → 2.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @intutic/cli
 
-> AI governance control plane for developer workspaces.
+> AI governance for developer workspaces.
 
 Intutic intercepts agent-to-LLM traffic, enforces SOPs, detects anomalies, and tracks costs — all without changing how your team codes.
 
@@ -17,10 +17,13 @@ npx @intutic/cli init
 **5 minutes to your first governance verdict:**
 
 ```bash
+intutic init               # Detect harnesses, record them in ~/.intutic/config.json
+intutic gates install      # Write each harness's gate and rules file from .intutic/sops/
 intutic start              # Run the proxy standalone — no account needed
 intutic traces list        # See governance verdicts
 ```
 
+<!-- UNRELEASED:cloud
 **With a control plane:**
 
 ```bash
@@ -29,22 +32,27 @@ intutic init               # Detect harnesses, record them for sync
 intutic connect            # Start sync daemon — writes harness rules and gates
 intutic traces list        # See governance verdicts
 ```
+-->
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `intutic init` | Initialize workspace — detect harnesses, record them in `~/.intutic/config.json` |
-| `intutic start` | Start the proxy standalone — no account or control plane needed (`--port`, `--upstream-url`) |
-| `intutic login` | Authenticate with control plane (`--api-key`, `--control-plane-url`, `--dev`) |
-| `intutic logout` | Clear stored credentials |
+| `intutic init` | Initialize workspace — detect harnesses, record them in `~/.intutic/config.json`, and offer to install the gates (`--gates`, `--no-gates`) |
+| `intutic gates install` | Write each recorded harness's gate and rules file from local SOPs (`.intutic/sops/`), with no control plane (`--harness`, `--route` to also write proxy routing while the proxy runs, `--dry-run`, `--workspace`) |
+| `intutic start` | Start the proxy standalone — no account or control plane needed; refreshes the installed gates when `.intutic/sops/` changes (`--port`, `--upstream-url`, `--no-gates`) |
 | `intutic status` | Show workspace status — auth, harnesses, sync state |
-| `intutic whoami` | Show current authenticated identity |
-| `intutic connect` | Start sync daemon — bidirectional config sync (`--interval`) |
-| `intutic disconnect` | Undo `intutic connect` — restore the harness configs it changed, remove its services, log out (`--harness`, `--dry-run`, `--keep-login`) |
+| `intutic disconnect` | Undo `intutic gates install` — restore the harness configs it changed (`--harness`, `--dry-run`, `--keep-login`) |
 | `intutic doctor` | Diagnose workspace health — proxy, auth, daemon, configs, logs |
 | `intutic traces list` | List execution traces (`--limit`, `--since`, `--action` with a control plane, `--verdict` without one, `--model`, `--json`) |
 | `intutic traces inspect <id>` | Show full detail of a single trace |
+<!-- UNRELEASED:cloud
+| `intutic login` | Authenticate with control plane (`--api-key`, `--control-plane-url`, `--dev`) |
+| `intutic logout` | Clear stored credentials |
+| `intutic whoami` | Show current authenticated identity |
+| `intutic connect` | Start sync daemon — bidirectional config sync (`--interval`) |
+| `intutic disconnect` | Also undoes `intutic connect`: removes its services and logs out unless `--keep-login` |
+-->
 
 ## Supported Harnesses
 
@@ -56,7 +64,7 @@ Intutic auto-detects and configures AI coding harnesses, among them:
 | **Cursor** | `.cursor/` or `.cursorrules` in the workspace, or `~/.cursor/` | `.cursor/rules/intutic-governance.mdc` + gate in `.cursor/hooks.json` |
 | **Aider** | `.aider.conf.yml` in the workspace | `.intutic/aider-sops.md`, loaded by `read:` in `.aider.conf.yml` |
 | **Antigravity** | `~/.gemini/antigravity*/`, `.agents/hooks.json`, `.gemini/` in the workspace, or `antigravity` / `gemini` on PATH | `GEMINI.md` section + `PreToolUse` gate in `~/.gemini/config/hooks.json` (Gemini CLI: `BeforeTool` gate in `~/.gemini/settings.json`) |
-| **Codex** | `codex` on PATH, or `CODEX_HOME` set | `AGENTS.md` section + gate in `.codex/hooks.json`; proxy routing in `~/.codex/config.toml` |
+| **Codex** | `codex` on PATH, or `CODEX_HOME` set | `AGENTS.md` section + gate in `.codex/hooks.json`; proxy routing in `~/.codex/config.toml` (with `--route`) |
 | **n8n** | Running n8n instance (`N8N_URL`, default `http://localhost:5678`) | Workflow JSON file + external hook gate `~/.intutic/hooks/n8n-governance-hook.js` |
 | **OpenClaw** | `~/.openclaw/` or `.openclaw/openclaw.json` | `AGENTS.md` section in its agent workspace + `~/.intutic/hooks/openclaw/intutic-governance.cjs` (plugin gate, listed in `~/.openclaw/openclaw.json`) |
 | **Hermes** | `~/.hermes/` or `.hermes/config.yaml` | `AGENTS.md` section + `hooks.pre_tool_call` gate in `~/.hermes/config.yaml` |
@@ -94,10 +102,11 @@ Credentials are stored at `~/.intutic/credentials.json` (mode `0600`).
 
 | Variable | Description |
 |----------|-------------|
-| `INTUTIC_CONTROL_PLANE_URL` | Control plane URL for this shell (overrides the one `intutic login --control-plane-url` saved) |
+| `INTUTIC_CONTROL_PLANE_URL` | Control plane URL for this shell (overrides the one a control-plane login saved) |
 | `INTUTIC_DEV` | `1` targets the local control plane (`http://localhost:3001`), like `--dev` |
 | `INTUTIC_PROXY_URL` | Local proxy URL; its port is the proxy port (default `4000`) |
 
+<!-- UNRELEASED:cloud
 For non-interactive auth, use `intutic login --api-key vk_...`.
 
 ### Development Mode
@@ -109,6 +118,7 @@ intutic login --dev
 intutic connect --dev
 intutic traces list --dev
 ```
+-->
 
 ## Documentation
 

package/dist/cli.js

@@ -9,8 +9,9 @@
  *
  * @module
  */
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { createRequire } from 'node:module';
+import { CLOUD_RELEASED, CONTROL_PLANE_PRODUCT_RELEASED, HOSTED_CONTROL_PLANE_URL, SELF_HOST_RELEASED, } from '@intutic/shared-types';
 import { DEFAULT_SANDBOX_IMAGE } from './lib/sandbox/image.js';
 // Read the version from package.json rather than repeating it here. The literal
 // that used to live below said 1.6.0 for three releases running, so
@@ -20,13 +21,37 @@ import { DEFAULT_SANDBOX_IMAGE } from './lib/sandbox/image.js';
 // but JSON imports still need an assertion on older runtimes.
 const { version } = createRequire(import.meta.url)('../package.json');
 const program = new Command();
+// Release flags (packages/shared-types/src/release.ts). A command that only
+// works against a control plane, or only in the self-hosted distribution, is
+// left out of help until that product is released. Hidden is all it is: the
+// command still parses and runs, so staging and existing users are unaffected.
+const needsControlPlane = { hidden: !CONTROL_PLANE_PRODUCT_RELEASED };
+const needsSelfHost = { hidden: !SELF_HOST_RELEASED };
+/** An option of a visible command that only does anything against a control plane. */
+function controlPlaneOption(flags, description) {
+    const option = new Option(flags, description);
+    return CONTROL_PLANE_PRODUCT_RELEASED ? option : option.hideHelp();
+}
+// A command that needs a control plane, run with none configured, throws
+// NoControlPlaneError (config/paths.ts) from an async action. Say that plainly
+// rather than as an unhandled rejection with a stack; anything else still
+// crashes as before.
+process.on('unhandledRejection', (err) => {
+    if (err instanceof Error && err.name === 'NoControlPlaneError') {
+        console.error(err.message);
+        process.exit(1);
+    }
+    throw err;
+});
 // Positional options: `--version` and `--help` belong to the program only when
 // they come before a subcommand. Without this, commander matches program
 // options anywhere on the line, so a subcommand option named `--version` would
 // print the CLI version and exit before its command ever saw it.
 program
     .name('intutic')
-    .description('Intutic CLI — AI governance control plane for developer workspaces')
+    .description(CONTROL_PLANE_PRODUCT_RELEASED
+    ? 'Intutic CLI — AI governance control plane for developer workspaces'
+    : 'Intutic CLI — open-core AI governance for developer workspaces: a local proxy, gates and policy for coding agents')
     .version(version)
     .enablePositionalOptions();
 program
@@ -35,6 +60,8 @@ program
     .option('--dev', 'Use local control plane (http://localhost:3001)')
     .option('--git-hooks', 'Install the Intutic Git hooks without asking')
     .option('--no-git-hooks', 'Skip the Git hooks without asking (the default when stdin is not a terminal)')
+    .option('--gates', 'Install the harness gates (`intutic gates install`) without asking')
+    .option('--no-gates', 'Skip the harness gates without asking (the default when stdin is not a terminal)')
     .action(async (opts) => {
     const { runInit } = await import('./commands/init.js');
     await runInit(opts);
@@ -49,7 +76,7 @@ program
     await runSetup(opts);
 });
 const judgeCmd = program
-    .command('judge')
+    .command('judge', needsSelfHost)
     .description('Configure the LLM-as-judge path');
 judgeCmd
     .command('configure')
@@ -60,7 +87,7 @@ judgeCmd
     await runJudgeConfigure(opts);
 });
 program
-    .command('login')
+    .command('login', needsControlPlane)
     .description('Authenticate with the Intutic control plane')
     .option('--api-key <key>', 'Authenticate with an API key (vk_*)')
     .option('--control-plane-url <url>', 'Control plane to log in to (e.g. a self-hosted one); saved for every later command')
@@ -71,7 +98,7 @@ program
 });
 program
     .command('disconnect')
-    .description('Undo intutic connect: restore every harness config it changed, remove its services, and log out')
+    .description('Undo intutic connect or intutic gates install: restore every harness config they changed, remove the gates and services, and log out')
     .option('--harness <id>', 'Disconnect one harness only (credentials and services stay)')
     .option('--dry-run', 'Print exactly what would change, and change nothing')
     .option('--keep-login', 'Keep the stored credentials')
@@ -80,7 +107,7 @@ program
     await runDisconnect({ harness: opts.harness, dryRun: opts.dryRun, keepLogin: opts.keepLogin });
 });
 program
-    .command('logout')
+    .command('logout', needsControlPlane)
     .description('Clear stored credentials')
     .action(async () => {
     const { runLogout } = await import('./commands/logout.js');
@@ -111,7 +138,9 @@ program
 });
 const budgetCmd = program
     .command('budget')
-    .description('Check remaining daily/monthly budget and list active loops; set workspace, key and member budgets')
+    .description(CONTROL_PLANE_PRODUCT_RELEASED
+    ? 'Check remaining daily/monthly budget and list active loops; set workspace, key and member budgets'
+    : 'Check the local spending cap and what this machine has spent today')
     .option('--dev', 'Use local control plane (http://localhost:3001)')
     .option('--watch', 'Continuously print machine-local and workspace spend, one line per tick')
     .option('--interval <seconds>', 'Tick interval in seconds for --watch', String(5))
@@ -125,7 +154,7 @@ const budgetCmd = program
     await runBudget(opts);
 });
 budgetCmd
-    .command('set')
+    .command('set', needsControlPlane)
     .description("Set the workspace's daily and monthly caps, alert threshold and whether each cap refuses requests (OWNER, ADMIN)")
     .option('--daily <usd>', 'Daily cap in USD (0: no daily cap; default: back to the $100 default)')
     .option('--monthly <usd>', 'Monthly cap in USD (0: no monthly cap; default: back to the $500 default)')
@@ -141,7 +170,7 @@ budgetCmd
     await runBudgetSet(cmd.optsWithGlobals());
 });
 budgetCmd
-    .command('keys')
+    .command('keys', needsControlPlane)
     .description("Every virtual key's spend budgets, rate limit and spend today and this month")
     .option('--json', 'Output as JSON')
     .option('--dev', 'Use local control plane (http://localhost:3001)')
@@ -150,7 +179,7 @@ budgetCmd
     await runBudgetKeys(cmd.optsWithGlobals());
 });
 budgetCmd
-    .command('key <keyId>')
+    .command('key <keyId>', needsControlPlane)
     .description("Set a virtual key's spend budgets and rate limit (OWNER, ADMIN)")
     .option('--daily <usd>', 'Day budget in USD, or none to remove it')
     .option('--monthly <usd>', 'Month budget in USD, or none to remove it')
@@ -165,7 +194,7 @@ budgetCmd
     await runBudgetKey(keyId, cmd.optsWithGlobals());
 });
 budgetCmd
-    .command('members')
+    .command('members', needsControlPlane)
     .description("The default member budget, and each member's budgets and spend (Biz Org+)")
     .option('--json', 'Output as JSON')
     .option('--dev', 'Use local control plane (http://localhost:3001)')
@@ -174,7 +203,7 @@ budgetCmd
     await runBudgetMembers(cmd.optsWithGlobals());
 });
 budgetCmd
-    .command('member <memberId>')
+    .command('member <memberId>', needsControlPlane)
     .description("Set a member's spend budgets, or the default member budget with `default` (OWNER, ADMIN; Biz Org+)")
     .option('--daily <usd>', 'Day budget in USD, or none to remove it')
     .option('--monthly <usd>', 'Month budget in USD, or none to remove it')
@@ -187,7 +216,7 @@ budgetCmd
     await runBudgetMember(memberId, cmd.optsWithGlobals());
 });
 program
-    .command('predict-cost')
+    .command('predict-cost', needsControlPlane)
     .description('Pre-flight cost estimate for a prompt/task before it runs (requires `intutic login`). ' +
     "Estimates output tokens from the workspace's recorded usage and prices them with the same " +
     'rate table as every other cost figure the control plane reports.')
@@ -201,7 +230,7 @@ program
     await runPredictCost(opts);
 });
 const sopsCmd = program
-    .command('sops')
+    .command('sops', needsControlPlane)
     .description('Manage local and global SOP rules');
 sopsCmd
     .command('push <name>')
@@ -249,7 +278,7 @@ sopsCmd
 });
 // ── SOP Optimizer approval mode ──────────────────────────────────────────
 const optimizerCmd = program
-    .command('optimizer')
+    .command('optimizer', needsControlPlane)
     .description("Read and set the SOP Optimizer's approval mode (whether it may auto-apply strengthening proposals)");
 optimizerCmd
     .command('settings')
@@ -273,9 +302,9 @@ optimizerCmd
 });
 const policyCmd = program
     .command('policy')
-    .description('WASM rules and the policy snapshot');
+    .description(CONTROL_PLANE_PRODUCT_RELEASED ? 'WASM rules and the policy snapshot' : 'WASM rules: compile, test and install them locally');
 policyCmd
-    .command('snapshot')
+    .command('snapshot', needsControlPlane)
     .description('Compile workspace policy to ~/.intutic/hooks/policy-snapshot.rules — the file every gate reads.\n' +
     '\n' +
     '  Does only that. \'intutic connect\' writes it too, but as one step of\n' +
@@ -298,10 +327,10 @@ policyCmd
     .command('compile')
     .description('Compile an AssemblyScript rule to WASM (wraps asc)')
     .option('--src <path>', 'Rule source entry file (default: assembly/index.ts)')
-    .option('--out <path>', 'Output .wasm path (default: build/rule.wasm, or build/<candidate>.wasm with --candidate)')
+    .option('--out <path>', `Output .wasm path (default: build/rule.wasm${CONTROL_PLANE_PRODUCT_RELEASED ? ', or build/<candidate>.wasm with --candidate' : ''})`)
     .option('--debug', 'Include debug info and source maps')
-    .option('--candidate <id>', 'Compile a rule candidate from its source of record on the control plane (fetched and hash-verified; not with --src)')
-    .option('--upload', 'With --candidate: upload the bundle to the candidate with its source hash and print the gate results')
+    .addOption(controlPlaneOption('--candidate <id>', 'Compile a rule candidate from its source of record on the control plane (fetched and hash-verified; not with --src)'))
+    .addOption(controlPlaneOption('--upload', 'With --candidate: upload the bundle to the candidate with its source hash and print the gate results'))
     .option('--dev', 'Use local control plane (http://localhost:3001)')
     .action(async (opts) => {
     const { runPolicyCompile } = await import('./commands/policy.js');
@@ -325,7 +354,7 @@ policyCmd
     await runPolicyListLocal();
 });
 policyCmd
-    .command('replay <ruleId>')
+    .command('replay <ruleId>', needsControlPlane)
     .description("Replay a rule (installed or not) against this workspace's own recent traffic and report " +
     'what it would have done, without touching enforcement.')
     .option('--limit <n>', 'Max sampled contexts to replay against (default 500, capped at 5000)')
@@ -371,7 +400,7 @@ rulesCmd
 // `intutic sops` is files on disk; this namespace is the cited guardrails
 // extracted from policy documents and their shadow -> promote lifecycle.
 const guardrailsCmd = program
-    .command('guardrails')
+    .command('guardrails', needsControlPlane)
     .description('Policy documents, cited clauses and the guardrails compiled from them');
 const guardrailsSourcesCmd = guardrailsCmd
     .command('sources')
@@ -614,7 +643,7 @@ guardrailsCmd
     await runGuardrailsPull(opts);
 });
 program
-    .command('whoami')
+    .command('whoami', needsControlPlane)
     .description('Show current authenticated identity')
     .option('--dev', 'Use local control plane (http://localhost:3001)')
     .action(async (opts) => {
@@ -627,10 +656,30 @@ program
     .option('--port <port>', 'Proxy port (default: the port of $INTUTIC_PROXY_URL, else 4000)')
     .option('--valkey-port <port>', 'Valkey port', '6379')
     .option('--upstream-url <url>', 'Upstream LLM provider base URL')
+    .option('--no-gates', 'Do not refresh the local gates (`intutic gates install`) or watch .intutic/sops while the proxy runs')
     .action(async (opts) => {
     const { runStart } = await import('./commands/start.js');
     await runStart(opts);
 });
+const gatesCmd = program
+    .command('gates')
+    .description('Harness hook gates and rules files, without a control plane');
+gatesCmd
+    .command('install')
+    .description('Install the tool-call gate and rules file for each recorded harness, from this machine alone: ' +
+    'the built-in protections, the local .intutic/sops, and review_before: tokens (refused, as nothing can approve a hold)')
+    .option('--harness <id>', 'Only this harness (it must be recorded by `intutic init`, or pass --add)')
+    .option('--add', 'With --harness: record the harness in ~/.intutic/config.json if it is not')
+    .option('--route', "Also point the harnesses' LLM traffic at the local proxy, which must then be running (e.g. `intutic daemon install --proxy`)")
+    .option('--dry-run', 'Print what would be written, and write nothing')
+    .option('--workspace <path>', 'Workspace to write into (default: the one `intutic init` recorded)')
+    .action(async (opts) => {
+    // The writers log each file at info, as JSON; the command prints its own
+    // list. Warnings (a file left alone because it does not parse) still show.
+    process.env.LOG_LEVEL ??= 'warn';
+    const { runGatesInstall } = await import('./commands/gates.js');
+    await runGatesInstall(opts);
+});
 // L2 mandatory egress firewall. Makes the governing proxy
 // non-optional: default-deny host egress to everything except the proxy, DNS,
 // and declared infra. apply/remove need root; generate/status do not.
@@ -657,7 +706,7 @@ for (const [action, desc] of [
     });
 }
 enforceCmd
-    .command('report')
+    .command('report', needsControlPlane)
     .description('Report locally recorded enforcement state (firewall/CA-trust/system-hooks) to the control plane. ' +
     'No privilege needed — for when apply/remove ran elevated and could not reach stored credentials.')
     .action(async () => {
@@ -670,7 +719,7 @@ enforceCmd
 // tools/scripts/intutic-enterprise-install.sh, an unrelated air-gapped
 // docker-compose installer. Does not touch the host firewall; see `enforce`.
 const enterpriseCmd = program
-    .command('enterprise')
+    .command('enterprise', needsControlPlane)
     .description('Enterprise fleet rollout: CA trust, Cursor system hooks, MDM manifests');
 enterpriseCmd
     .command('install')
@@ -709,7 +758,7 @@ envCmd
     await runEnvClear();
 });
 program
-    .command('connect')
+    .command('connect', needsControlPlane)
     .description('Start sync daemon — bidirectional config sync with control plane (requires an account)')
     .option('--dev', 'Use local control plane (http://localhost:3001)')
     .option('--interval <ms>', 'Poll interval in milliseconds', '30000')
@@ -721,7 +770,7 @@ program
     await runConnect(opts);
 });
 program
-    .command('sync-context')
+    .command('sync-context', needsControlPlane)
     .description('Record the Git branch and commit in .intutic/git-context.json, which a running `intutic connect` reports')
     .option('--git', 'Read the branch and commit from the repository (for any not given below)')
     .option('--branch <name>', 'Current Git branch name')
@@ -731,7 +780,7 @@ program
     await runSyncContext(opts);
 });
 program
-    .command('decisions-log-refresh')
+    .command('decisions-log-refresh', needsControlPlane)
     .description('One-shot refresh of the governed decisions log (.intutic/DECISIONS.md, and the recent ' +
     'entries in each governed harness\'s instructions file) — no-ops if decisionsLogEnabled is off. Invoked by the optional ' +
     'post-merge Git hook `intutic init` installs; safe to run manually.')
@@ -833,7 +882,7 @@ traces
 });
 // ── Findings (detector_findings adjudication) ───────────────────────────────
 const findings = program
-    .command('findings')
+    .command('findings', needsControlPlane)
     .description('Query and adjudicate detector findings — the TP/FP labeling surface');
 findings
     .command('list')
@@ -880,7 +929,7 @@ findings
 });
 // ── Governance incidents ───────────────────────────────────────────────────
 const incidentsCmd = program
-    .command('incidents')
+    .command('incidents', needsControlPlane)
     .description('Governance incidents, as on Findings › Incidents (OWNER, ADMIN, EM)');
 incidentsCmd
     .command('list')
@@ -907,7 +956,7 @@ incidentsCmd
 });
 // ── Trace integrity ────────────────────────────────────────────────────────
 const integrity = program
-    .command('integrity')
+    .command('integrity', needsControlPlane)
     .description('Verify sealed trace roots — list, re-derive, walk the root chain, and walk the config snapshot chain');
 integrity
     .command('roots')
@@ -950,7 +999,7 @@ integrity
 });
 // ── Routing reports ─────────────────────────────────────────────────────────
 const routing = program
-    .command('routing')
+    .command('routing', needsControlPlane)
     .description('Read-only reports for the routing subsystem');
 routing
     .command('adoption-report')
@@ -989,7 +1038,7 @@ function defineDaemonInstall(cmd) {
         '  Use \'intutic daemon stop\' or \'intutic daemon uninstall\'.')
         .option('--workspace-id <id>', 'Workspace ID (e.g. wk_xxxx) — required unless --proxy')
         .option('--api-key <key>', 'Workspace API key (e.g. vk_xxxx) — required unless --proxy')
-        .option('--control-plane-url <url>', 'Control plane the daemon connects to (default: $INTUTIC_CONTROL_PLANE_URL, then a workspace set up with `intutic init --dev`, then the URL saved by `intutic login`, then https://api.intutic.ai)')
+        .addOption(controlPlaneOption('--control-plane-url <url>', `Control plane the daemon connects to (default: $INTUTIC_CONTROL_PLANE_URL, then a workspace set up with \`intutic init --dev\`, then the URL saved by \`intutic login\`${CLOUD_RELEASED ? `, then ${HOSTED_CONTROL_PLANE_URL}` : ''})`))
         .option('--binary-path <path>', 'Path to intutic CLI binary (defaults to current process); with --proxy, absolute path to intutic-proxy')
         .option('--dry-run', 'Print what would be done without writing files')
         .option('--system', 'Install as a system-level service (LaunchDaemon on macOS, systemd system unit on Linux)')
@@ -1122,7 +1171,7 @@ skillCmd
 });
 // ── Loop commands ──────────────────────────────────────────────────────────
 const loopCmd = program
-    .command('loop')
+    .command('loop', needsControlPlane)
     .description('Manage and execute recursive agent loops with budget limits');
 loopCmd
     .command('start')
@@ -1190,7 +1239,7 @@ loopCmd
 // module doc for why `intutic loop review` was never the right command for
 // this — it addresses a different id space (Loop Runs, not decisions).
 const decisionCmd = program
-    .command('decision')
+    .command('decision', needsControlPlane)
     .description('Approve or reject a decision (e.g. a review_before hold) held for human review');
 decisionCmd
     .command('approve <holdId>')
@@ -1216,7 +1265,7 @@ decisionCmd
 // hand-written curl against services/control-plane/src/routes/gateways.ts —
 // see commands/gateway.ts's module doc.
 const gatewayCmd = program
-    .command('gateway')
+    .command('gateway', needsControlPlane)
     .description('Manage self-hosted gateway registrations (Docker / Kubernetes / bare metal)');
 gatewayCmd
     .command('register')
@@ -1314,7 +1363,7 @@ gatewayCmd
 // Provision a workspace's own upstream provider keys — the BYO-key wizard's
 // API, previously dashboard-only. See commands/credentials.ts's module doc.
 const credentialsCmd = program
-    .command('credentials')
+    .command('credentials', needsControlPlane)
     .description('Manage this workspace\'s own upstream provider API keys (BYO-key)');
 credentialsCmd
     .command('list')
@@ -1358,7 +1407,7 @@ credentialsCmd
 // "CLI mints, dashboard audits": this is the mint/inspect half. See
 // commands/attenuate.ts's module doc.
 const attenuateCmd = program
-    .command('attenuate')
+    .command('attenuate', needsControlPlane)
     .description('Attenuate one of your API keys to a child key with narrower scopes (and an optional TTL)')
     .option('--parent-key <keyId>', 'Parent API key ID to attenuate')
     .option('--caps <scopes>', 'Comma-separated API key scopes for the child key (e.g. gateway:use,traces:read); each must be granted by the parent key')
@@ -1378,7 +1427,7 @@ attenuateCmd
 });
 // ── API keys and their scopes ────────────────────────────────────────────
 const keysCmd = program
-    .command('keys')
+    .command('keys', needsControlPlane)
     .description('List, create, re-scope and revoke your API keys');
 keysCmd
     .command('list')
@@ -1423,7 +1472,7 @@ keysCmd
 });
 // ── Org signup + team management ─────────────────────────────────────────
 const orgCmd = program
-    .command('org')
+    .command('org', needsControlPlane)
     .description('Create and manage orgs');
 orgCmd
     .command('create')
@@ -1438,7 +1487,7 @@ orgCmd
     await runOrgCreate(opts);
 });
 const teamCmd = program
-    .command('team')
+    .command('team', needsControlPlane)
     .description('Manage teams and workspaces under an org');
 teamCmd
     .command('list')
@@ -1487,7 +1536,7 @@ teamCmd
 // route. Previously dashboard-only. See commands/apiCommand.ts for the shape
 // they share.
 const settingsCmd = program
-    .command('settings')
+    .command('settings', needsControlPlane)
     .description('Read and change workspace settings (MCP policy, budgets, group policy, config content upload, ...)');
 settingsCmd
     .command('get [key]')
@@ -1509,7 +1558,7 @@ settingsCmd
     await runSettingsSet(key, value, opts);
 });
 const mcpCmd = program
-    .command('mcp')
+    .command('mcp', needsControlPlane)
     .description('Review the MCP servers the workspace\'s MCP proxies have seen, and decide on them');
 mcpCmd
     .command('list')
@@ -1550,7 +1599,7 @@ for (const [action, enabled, desc] of [
     });
 }
 const notificationsCmd = program
-    .command('notifications')
+    .command('notifications', needsControlPlane)
     .description('Manage notification rules: which events go to Slack, email, a webhook or PagerDuty');
 function ruleOptions(cmd) {
     return cmd
@@ -1612,7 +1661,7 @@ notificationsCmd
     await runNotificationsRotateSecret(ruleId, opts);
 });
 const siemCmd = program
-    .command('siem')
+    .command('siem', needsControlPlane)
     .description('Manage SIEM export destinations and the event sources each receives');
 function destinationOptions(cmd) {
     return cmd
@@ -1687,7 +1736,7 @@ siemCmd
     await runSiemRotateSecret(destinationId, opts);
 });
 const tasksCmd = program
-    .command('tasks')
+    .command('tasks', needsControlPlane)
     .description('Manage task-management connections (Jira Cloud, Linear, PagerDuty) that attach ticket context to sessions');
 tasksCmd
     .command('list')
@@ -1732,7 +1781,7 @@ tasksCmd
     await runTasksRemove(connectionId, opts);
 });
 const complianceCmd = program
-    .command('compliance')
+    .command('compliance', needsControlPlane)
     .description('Compliance framework reports and the evidence archive');
 complianceCmd
     .command('coverage <framework_id>')
@@ -1777,7 +1826,7 @@ complianceCmd
     await runComplianceVerify(file, opts);
 });
 const usageCmd = program
-    .command('usage')
+    .command('usage', needsControlPlane)
     .description('LLM usage across the fleet, by member, team, branch, commit or pull request');
 for (const [view, handler, desc] of [
     ['members', 'runUsageMembers', 'Usage per member'],
@@ -1808,7 +1857,7 @@ usageCmd
     await runUsagePullRequests(opts);
 });
 const githubWebhookCmd = program
-    .command('github')
+    .command('github', needsControlPlane)
     .description('GitHub integration for cost per pull request')
     .command('webhook')
     .description('The pull-request webhook: payload URL and signing secret');
@@ -1831,7 +1880,7 @@ githubWebhookCmd
     await runGithubWebhookRotateSecret(opts);
 });
 const inventoryCmd = program
-    .command('inventory')
+    .command('inventory', needsControlPlane)
     .description('AI harnesses, MCP servers and skills on connected developer machines, governed or not');
 inventoryCmd
     .command('summary')
@@ -1893,7 +1942,7 @@ inventoryCmd
     await runInventoryDisconnects(opts);
 });
 program
-    .command('gate-liveness')
+    .command('gate-liveness', needsControlPlane)
     .description('Whether each installed harness\'s gate is reporting, and any open silent-gate alert')
     .option('--json', 'Output as JSON')
     .option('--dev', 'Use local control plane (http://localhost:3001)')