@qbts/cli

qbts — a two-tier execution CLI. Classical. Deterministic. Shipped.

qbts has two tiers behind one command:

• TIER-BASE — a classical / AI task-pipeline engine. Define an ordered pipeline of shell and ai steps and run it, with per-step retries and a run receipt. The non-quantum counterpart to @qbtz/cli (the quantum orchestrator).
• TIER-FABRIC — a credential-free client of the qbits coordination fabric: author and submit a governed run-config (objective + repositories + verification/canary/rollback + budgets) to a BigBrain-fenced, MANGOS-routed, phased durable orchestration, and read its status.

Install / use

npx @qbts/cli --help
# or
npm i -g @qbts/cli && qbts --help

Node ≥ 20.

TIER-BASE — task pipelines

qbts init                 # scaffold qbts.json (a runnable starter pipeline)
qbts validate             # validate qbts.json
qbts run                  # run it (writes qbts-run-receipt.json)
qbts run --dry-run        # print the steps without executing

qbts.json is a simple ordered pipeline:

{
  "qbts": "1",
  "name": "my-pipeline",
  "steps": [
    { "name": "test", "kind": "shell", "run": ["node", "--test"], "retries": 1 },
    { "name": "fetch", "kind": "http", "url": "https://api.example.com/health", "expectStatus": 200 },
    { "name": "record", "kind": "write", "path": "status.txt", "content": "ok" },
    { "name": "summarize", "kind": "ai", "prompt": "Summarize the test output.", "continueOnError": true }
  ]
}

Four step kinds:

• shell — run an argv locally (run), with retries.
• http — make a request (url, method, headers, body); assert expectStatus or any 2xx.
• write — write content to path (relative to the pipeline dir).
• ai — call an AI gateway when configured (QBTS_AI_URL / QBTS_AI_KEY) and dry-run otherwise.

Any step can set continueOnError. qbts run --dry-run prints every step without executing — so a pipeline is always safe to preview anywhere.

TIER-FABRIC — the qbits coordination fabric

qbts fabric init                  # scaffold qbits-run-config.json (read-only starter)
qbts fabric validate              # validate it against the qbits-v2 contract
qbts fabric plan                  # preview objective / budgets / phases (no submit)
qbts fabric submit --dry-run      # print the exact submission
qbts fabric submit                # submit to the configured control plane (needs credentials)
qbts fabric status                # probe the transport
qbts fabric status --manifest run-manifest.json   # summarize a run manifest

A run-config is the operator-authored input to the fabric:

{
  "objective": "Plan the change across the listed repositories; stop at READY_FOR_APPROVAL.",
  "workspace": "/abs/path/to/workspace",
  "repositories": ["/abs/path/to/repo"],
  "verificationCommands": [["/usr/bin/node", "--version"]],
  "budgets": { "inputTokens": 500000, "outputTokens": 120000, "estimatedCostUsd": 12 },
  "readOnly": true
}

When readOnly is false, canaryCommands and rollbackCommands become required — the client enforces this and the other contract invariants locally before you ever submit.

Configuration (all env-driven — nothing is bundled)

| Variable | Tier | Purpose | Default | | --- | --- | --- | --- | | QBTS_AI_URL / QBTS_AI_KEY | base | AI gateway for ai steps | — (dry-run if unset) | | QBITS_BIGBRAIN_URL | fabric | control-plane task endpoint base | http://127.0.0.1:3111 | | QBITS_MANGOS_URL | fabric | routing endpoint (probe) | http://127.0.0.1:3151 | | QBITS_BROKER_API_KEY | fabric | X-API-Key for submit | — (dry-run if unset) | | QBITS_INTERNAL_TOKEN | fabric | Bearer for submit | — (dry-run if unset) |

The fabric client talks only to endpoints you configure and carries no credentials of its own; the private control plane stays private.

License

MIT © Dane Anthony Cooper