CLI Reference

Licensing

Every command except auth and the host-invoked hook requires a valid license. auth is a necessity rather than a policy choice: auth activate is how a machine becomes licensed, so gating it would make the license unobtainable; hook is invoked by your AI host and never refuses. Activate before anything else:

cortexbuild auth activate --key <token>
cortexbuild auth status          # confirm before moving on

--help needs no license, so cortexbuild <command> --help always works.

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).

Flags

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), refresh (renew the signed lease), deactivate (free this device's seat), status, logout.	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).	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.	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 and local-only.	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 and deterministic.	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.	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), plus the feedback capture channel: submit records "something is not working" (--kind bug), "could be done better" (--kind improvement — the AI tool files these itself via --source ai-tool), and task-completion ratings (--kind experience --rating 1..5); list shows records + the average rating. Rides the telemetry pipeline: local ledger always, best-effort push to the org collector, secret/injection-shaped text refused. orchestrate run asks for a rating after interactive runs (--no-feedback to skip; never prompts non-interactive sessions).	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 (PROJECT_PROFILE.yaml) — the evidence that drives rule activation. harvest (offline, propose-only; --write to apply), score (risk-weighted completeness + gaps report; idempotent on disk since 0.2.14), validate (schema + controlled-vocabulary check), interview (fill gaps — it does not correct an already-set field), set <field> <value> (correct a field that is already set, recorded with human provenance), gate (advisory pre-work check). Offline, deterministic.	LIVE
orchestrate	Drive a task through the governed agent waves: run (single task; --dry-run simulates offline with no LLM), batch (a backlog JSON), tiers (which model tier each agent would run on and why — no LLM call, no spend), autonomy (the effective approval matrix). Tier routing honours the allocation.objective in .cortexbuild/llm-config.yaml, and holds a risky task off the cheapest tier whatever that objective says. See Configure Your Model.	LIVE
task	The committed task store (offline, no LLM) — one task truth, bridged both ways. Inbound: author a task by hand, or import a tracker backlog JSON (idempotent; provenance recorded in the intent). Governance: approve then dispatch — consent-gated, audited transitions; every executor gets the same contract. Outbound: distribute renders the workflow slice + evidence-pack contract for an external harness, or run it in-process with orchestrate run and its --from-task flag (requires dispatched; --dry-run simulates from any status; risk/flags inferred from the task's own text, explicit flags win). list reads the store; bind-check dry-runs the loopback gate. HTTP serving is server seam ([server] extra); everything here works on the default install. Not to be confused with tasks (plural) — tracker tickets assigned to you.	LIVE
precedence	Shared precedence + provenance model.	LIVE
cost	What CortexBuild costs an AI coding session. footprint measures the render set against Anthropic's documented context budgets (200-line CLAUDE.md; 15,000-token combined subagent descriptions) and classifies every surface by when it loads; baseline records the current figures to .cortexbuild/cost-baseline.json; report shows the delta. --fail-over-budget / --fail-on-regression make either usable as a CI gate. Offline, deterministic, no LLM. Not to be confused with context, which is the business context profile.	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
hook	One host-agnostic EXECUTABLE hook (session-start | stop | pre-edit) invoked by every rendered per-host hook config — reads the host's JSON on stdin, writes the host's expected output on stdout/exit-code. Never invoked by a person directly; see Executable Hooks.	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

Correcting a project profile

The interview only fills gaps. Against an already-populated field it applies nothing and reports Applied 0 field(s) — so context set is the sanctioned way to fix a value that is set but wrong. Hand-editing PROJECT_PROFILE.yaml is not.

cortexbuild context validate -r .                  # what is actually wrong
cortexbuild context set deployment_model hybrid -r .
cortexbuild context set compliance "GDPR,SOC 2,ISO 27001" -r .

compliance is comma-separated and validated against a controlled vocabulary. Near-misses are canonicalised — SOC 2 becomes SOC2, ISO 27001 becomes ISO-27001 — because a value stored verbatim looks human-confirmed while matching no rule and therefore activating nothing. An unrecognised regime is refused rather than partially applied; use other to record an obligation that has no rule mapping.

Setting compliance records human confirmation, which is what makes the regimes eligible to activate compliance rules. Values harvested at moderate confidence never activate rules on their own.

Available since 0.2.9; compliance became settable in 0.2.15.

What CortexBuild costs your AI sessions

Governance is carried by every session in every governed repo, so its size is a cost your team pays. cortexbuild cost measures it rather than assuming it.

cortexbuild cost footprint        # what does it cost today?
cortexbuild cost baseline         # record that, and commit the file
# ...make changes...
cortexbuild cost report           # did it actually go down?

How Claude Code loads it. CLAUDE.md sits in the project context layer of a three-layer cached prefix, so after the first request it is billed at the cache-read rate — not full price on every turn. It still costs, for four documented reasons: the layer is rebuilt at every session start and after every /clear and /compact (a cache write at 1.25×, and Anthropic recommends clearing between tasks); it is on the wire in every request regardless; every subagent loads its own copy into its own context; and "longer files consume more context and reduce adherence."

Cache stability matters more than size. Anthropic's prefix match is exact, with no per-file or per-segment caching, and "cache hits are not deducted against your rate limit." Anything that changes the rendered bytes invalidates the prefix and converts cheap reads into full-price input, so render output is byte-deterministic and a test holds it there.

Two mechanisms keep the always-loaded surface small. Rules wrap explanation in <!-- rationale:start --> / <!-- rationale:end -->; that prose is dropped from CLAUDE.md and kept in full in .cortexbuild/INSTRUCTIONS.md. Rules that declare paths: frontmatter render to .claude/rules/ and load only when a matching file is read — arriving whole, instead of as a name in a list.

Measuring the mix. telemetry record accepts --input-tokens, --output-tokens, --cache-read-tokens and --cache-creation-tokens, mapping onto Claude Code's OpenTelemetry claude_code.token.usage attributes. telemetry show reports the resulting prompt-cache hit rate.

Anthropic publishes no numeric Pro/Max weekly cap and no unit for it, so every figure here is a relative measurement. Nothing reports "you have N left".

Determinism & safety notes

• The deterministic, offline, no-LLM checks are eval, render --check, conformance, feedback, debt-heatmap, cost, 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) — 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
• Log out (removes the cached license from this machine):
• cortexbuild auth logout

CI/non-interactive usage: activate once (or set the token via your CI secret store) and confirm with cortexbuild auth status --json.

Every user is licensed — including free

free is a plan we issue, not the state of having no licence. That is a deliberate design choice rather than a formality: an unlicensed machine has no org, no user and no plan, so nothing it does can be attributed. Licensing everyone is what makes fleet and utilisation reporting possible at all.

Two consequences worth knowing:

• A registered free user and a broken install both resolve to free. Only one of them is licensed. Every surface reports licensed alongside the plan, so the two are never presented as the same thing — cortexbuild auth entitlements exits non-zero when the licence does not verify.
• Free licences carry the same org, user and device cap as any other plan. They are ordinary licences with a smaller feature entitlement set than the paid plans.

Getting a licence

Your administrator issues licences for your organisation from the admin portal (Licenses → Issue a license), and sends you the activation token. Activate it with:

cortexbuild auth activate --key <token> --url https://license.cortexbuild.dev
cortexbuild auth status          # confirm it verifies on THIS install

If you lose the token, ask your administrator to rotate it.

Next

• Onboard Your Repo — the step-by-step walkthrough.
• What is CortexBuild? — the concepts.