Skip to content

CLI Reference

In plain English

This is the full set of cortexbuild commands you can run today. Every row is a real, registered command. The Status column is honest about what is fully live, what is opt-in (you must ask for it), and what is advisory (proposes changes you approve — it never acts on its own).

Pre-alpha

cortexbuild-core is 0.0.1 / pre-alpha and dev-install only (not on PyPI). See Install. Run cortexbuild <command> --help for the authoritative flags of any command below.

Status legend

Tag Meaning
LIVE Fully implemented; deterministic and runs offline unless noted.
opt-in Off by default; you explicitly enable it (and it stays propose-only).
advisory Proposes/scores only; applies nothing without an explicit approval gate.

Commands

Command What it does Status
version Print the installed CortexBuild version. LIVE
info Print high-level information about this install. LIVE
auth License auth for registered usage: activate (online device activation with --url, or a legacy local token without it), refresh (renew the signed lease), deactivate (free this device's seat), status, logout. LIVE
license Operator license administration (license-exempt): keygen (Ed25519 signing keypair), issue, reassign, revoke, list. Manages the self-hosted license service store. LIVE
init run <TARGET> Brownfield onboarding pipeline (Pass 1–5) — analyse a local path or git URL into .cortexbuild/. LIVE
onboard Interactive project-context wizard (Harvest → Score → Interview → Mission → Render → Lifecycle). LIVE
render Render the rule single-source-of-truth into every AI-tool surface (Copilot, Claude, Codex, Cursor). LIVE
render --check CI drift gate — exits 1 if any rendered file is stale; writes nothing. Note: the framework version is stamped into every rendered file, so this reports drift after any version bump even when no rule changed — it is not the tool for deciding whether an upgrade needs a re-render. Use upgrade for that. LIVE
upgrade One-command, validated, reversible version upgrade: upgrade (preview), --apply (snapshot → render → validate), --rollback (byte-identical restore). Fails closed on hand-edited owned files. See Upgrade an Onboarded Repo. LIVE
doctor Read-only agent-invocation health check — reports whether each always-on instruction surface (copilot-instructions.md, CLAUDE.md, AGENTS.md) carries the governed-workflow default-routing directive, with a fix hint (--json, --strict). License-exempt. LIVE
usage Read-only local usage ledger inspection: report [--by-user] (per-user ROI rollup), whoami (transparency — which identity + gates apply), and push (consent-gated, enterprise-only per-user rollup push to the hosted org collector; dry-run by default). Opt-in, PII-free, pseudonymous by default. LIVE
verify Read-only OWASP Agentic Top 10 (ASI01–ASI10) self-assessment — per-risk coverage with per-control evidence (--json, --strict). Honest full/partial/gap. License-exempt. LIVE
graph Keep the repo code graph current: status (fresh/stale/absent), update (incremental — rebuilds only when sources changed; --force), show (print GRAPH_REPORT.md). Offline, local-only, license-exempt. LIVE
workspace Control-plane cross-repo dependency graph: graph (infer feature dependencies across repos from published-package ↔ dependency matching, edges tagged EXTRACTED/INFERRED; --write, --repo, --json) and status (list member repos). Offline, deterministic, license-exempt. LIVE
features Feature catalog + utilization: every governed feature with tier, entitlement status, and usage (used / unused-entitled / last-used). --unused filters to entitled-but-unused; --json. Read-only, license-exempt. LIVE
mcp Read-only MCP server surface: serve (stdio JSON-RPC for an IDE/agent host), tools, call, prompts, prompt. Projects .cortexbuild/ artefacts + agent personas; no write, no egress. See MCP & A2A integration. opt-in
a2a Emit the read-only A2A Agent Card (a2a card [--write] [--url]) so other agents can discover CortexBuild's roster + read-only skills. Discovery card only — not a live endpoint. See MCP & A2A integration. opt-in
memory Portable shared-memory identity: namespaces (show the dual-read order), migrate (non-destructive forward-copy to the canonical namespace), report (metadata-only rollup — counts by kind + by author + session continuity), and session save\|list\|restore (cross-device + cross-user working-context handoff — summary/tag-only, consent-gated when hosted). LIVE
ledger Recurrence-ledger management: init, add, list, show, close, set-status, sweep. LIVE
adopt Discover + quarantine pre-existing artefacts with provenance. LIVE
reconcile Reconcile conflicts and write a MERGE_REPORT.md. LIVE
standards Pull/sync org standards and run the drift gate. LIVE
conformance Deterministic conformance maturity report (no LLM). LIVE
report ROI / insights report with the conformance trend. LIVE
feedback Deterministic feedback synthesis (no LLM). LIVE
eval Offline eval harness — deterministic, no-LLM conformance scoring, appended to a hash-chained trend store. LIVE (offline)
remediation Synthesise corrective proposals; remediation apply previews by default and applies only under an explicit --approve gate (snapshots first, byte-reversible, never auto-merges). advisory
rollout Multi-repo / monorepo / org rollout. LIVE
export Deterministic SSoT marketplace export. LIVE
publish Native marketplace publishing (Claude/Gemini). Dry-run by default — emits a deterministic publish-plan with zero egress; a real upload needs explicit --publish + credentials + a scoped consent through the egress choke-point. opt-in
context Project-context profile schema + I/O. LIVE
precedence Shared precedence + provenance model. LIVE
lifecycle Rule lifecycle management. LIVE
skills Skill extraction from history — propose-only. opt-in
synthesize-rules Pass-3 rule synthesis (LLM-assisted) — propose-only, never enforced silently. opt-in
debt-heatmap Pass-4 technical-debt heatmap (no LLM). LIVE
session-start Session-start ledger-consult hook — surface live recurrence-ledger entries before acting. LIVE
session-handshake Boot the cross-tool session bundle (ledger + profile + shared-memory digest); deterministic and offline. LIVE
self-bootstrap Render CortexBuild's own agent personas + pointer Copilot instructions into <repo>/.github/. LIVE
eject Reversibly remove CortexBuild artefacts from a repo (--dry-run, --keep-backups, --yes). LIVE

Determinism & safety notes

  • The deterministic, offline, no-LLM checks are eval, render --check, conformance, feedback, debt-heatmap, and the recurrence-ledger guards. They produce the same result no matter which model produced the change under review, and they flag failures — they do not enforce a merge by themselves. Your existing approvals decide what lands.
  • remediation is advisory and reversible: it writes a reviewable plan and applies nothing unless you pass --approve; every applied remediation snapshots the surface set first and is byte-reversible.
  • synthesize-rules and skills are opt-in and propose-only — they draft candidates for you to accept or reject; nothing is enforced silently.

Enterprise validation defaults

  • cortexbuild init run <local-repo> runs enterprise validation by default after onboarding.
  • The bundled checks are drift detection, standards-pack integrity, and conformance scoring.
  • cortexbuild init run supports --no-validate-enterprise and --enterprise-fail-under <score>.
  • cortexbuild lifecycle build includes enterprise validation by default.
  • Other lifecycle verbs can opt in with --validate-enterprise when you want the same checks.

Optional extras

Some capabilities live behind install extras (see Install):

  • [graph] — tree-sitter parsers for JavaScript, TypeScript, and Go (Python uses the standard-library ast and needs no extra).
  • [anthropic] / [gemini] — native Claude / Google Gemini adapters, alongside the built-in OpenAI-compatible adapter (any base_url). No native AWS Bedrock or Google Vertex adapter ships today; those clouds are reachable only through an OpenAI-compatible gateway.
  • [server] — opt-in HTTP transport over the task/execution seam; it writes a task single-source-of-truth under .cortexbuild/tasks/ and does not run agents in-process. Also serves the web-dashboard control plane (cortexbuild server control-plane) and the multi-tenant org collector (cortexbuild server org, Doc 5) — both loopback-only by default (a routable bind requires --allow-remote, refused fail-closed otherwise).
  • [ide] — read-only file-reader over .cortexbuild/ for IDE surfaces.
  • [mcp] — read-only MCP server surface (cortexbuild mcp serve). Pure stdio JSON-RPC; needs no third-party runtime dependency. Lets an IDE/agent host consult CortexBuild through the standard protocol.
  • [a2a] — read-only A2A Agent Card discovery surface (cortexbuild a2a card). The agent↔agent complement to [mcp] (agent↔tool).
  • [memory] — mem0-backed shared-memory adapter (the default local file backend needs no extra).
  • [signing] — Ed25519 signing/verification for standards packs.
  • [watch] — file-watch backend for conformance watch / standards watch.
  • [publish] — opt-in, gated native marketplace publishing (dry-run by default).

The [mcp], [a2a], [ide], and [publish] extras are install handles + opt-in seams: they pull no new third-party dependency. The default install binds no socket and performs no egress; each surface only activates when you explicitly launch it.

License auth (registered users)

CortexBuild uses Ed25519-signed licenses verified offline against an embedded public key (forge-proof). A license is user-mapped with a device-seat cap.

  • Online device activation (trusted) — binds this machine's seat and caches a signed license:
  • cortexbuild auth activate --key cblk_<token> --url https://<license-host>
  • Renew the lease (run before it expires; e.g. CI cron or on login):
  • cortexbuild auth refresh
  • Free this device's seat:
  • cortexbuild auth deactivate
  • Check effective status (shows trust, plan, lease):
  • cortexbuild auth status --json
  • Legacy local token (untrusted; CI / air-gapped dev only):
  • cortexbuild auth activate --key cbk_<org>_<expiryYYYYMMDD>_<plan> (no --url)
  • cortexbuild auth logout removes it

CI/non-interactive usage:

  • Set CORTEXBUILD_LICENSE_TOKEN to avoid interactive activation in runners (legacy untrusted token).
  • Require the trusted signed path: CORTEXBUILD_LICENSE_REQUIRE_SIGNED=1 refuses unsigned tokens.
  • Emergency bypass (dev/test only): CORTEXBUILD_LICENSE_BYPASS=1.

License administration (operators)

The license command group is license-exempt (operators need no license to issue them) and administers the self-hosted license service.

  • Mint the signing keypair (once): cortexbuild license keygen (embed the public key, keep the private key in your secret store).
  • Issue a user-mapped license: cortexbuild license issue --org <org> --user <user> --plan enterprise --max-devices 3 --expires <ISO> --store-root <path>
  • Reassign to a different user (resets seats): cortexbuild license reassign <license_id> --new-user <user> --store-root <path>
  • Revoke: cortexbuild license revoke <license_id> --store-root <path>
  • List with seat usage: cortexbuild license list [--org <org>] --store-root <path>

See the internal runbook docs/ops/DISTRIBUTION_AND_LICENSE_CHECK.md for the full operator playbook (key custody, rotation, distribution channels).

Next