core command reference
The consumer CLI, shipped in core-cli (this page: version 2.1.0, the released package). Most commands talk to a running CORE API. See the CLI overview for which binary does what.
31 commands.
| Group | Commands | Purpose |
|---|---|---|
code |
13 | Codebase quality, style, and verification operations. |
lane |
4 | Assisted Remediation Lane: work delegated findings under human-gated approval. |
project |
3 | Bring a repository under governance: scout, onboard, promote (BYOR). |
proposals |
7 | Operations for the A3 Autonomous Proposal system (propose, approve, execute). |
symbols |
3 | Operations for the symbol registry and Knowledge Graph identification. |
vectors |
1 | Semantic search over the governed repository's vector index. |
core code
Codebase quality, style, and verification operations.
core code actions
core code actions
List all registered Atomic Actions (Body Capabilities). Shows IDs, categories, and impact levels for autonomous building blocks.
core code audit-duplicates
core code audit-duplicates [OPTIONS]
Perform a semantic scan to find duplicate logic across the codebase. Helps enforce the 'dry_by_design' constitutional principle.
| Argument / option | Default | Description |
|---|---|---|
--threshold |
0.96 |
Similarity threshold (0.0-1.0). |
core code baseline
core code baseline [OPTIONS]
Create a secure checksum baseline of the current 'src/' directory. Run this before starting autonomous tasks.
| Argument / option | Default | Description |
|---|---|---|
--label, -l |
default |
Label for this baseline. |
core code bridges
core code bridges [OPTIONS]
List declared architecture bridge points.
Each bridge is a constitutionally-declared data-flow crossing where information moves between CORE layers. Use --consuming to find bridges that consume a specific data type.
Example: core code bridges --consuming AuditFinding
| Argument / option | Default | Description |
|---|---|---|
--consuming, -c |
Filter by consuming type (e.g. AuditFinding, Proposal). |
core code check-imports
core code check-imports
Verify all import statements resolve to existing modules.
Checks for: - F821: References to undefined names (moved/deleted modules) - F401: Stale imports left after refactoring
Enforces: - code.imports.must_resolve - code.imports.no_stale_namespace
core code docstrings
core code docstrings [OPTIONS]
Autonomously generate and inject missing docstrings using AI.
| Argument / option | Default | Description |
|---|---|---|
--write |
off | Apply changes. |
--limit |
3 |
Symbols to process. |
--file |
Target a single file (repo-relative). |
core code fix-atomic
core code fix-atomic [OPTIONS]
Heal violations in the Atomic Action pattern. Ensures @atomic_action decorators and ActionResult returns are present.
| Argument / option | Default | Description |
|---|---|---|
--write |
off | Apply fixes to atomic action patterns. |
core code format
core code format [OPTIONS]
Format code using Black and Ruff.
Defaults to dry-run mode. Use --write to apply changes.
| Argument / option | Default | Description |
|---|---|---|
--write |
off | Apply formatting changes to disk. |
core code format-imports
core code format-imports [OPTIONS]
Sort and group Python imports according to PEP 8 / Constitutional standards. Uses Ruff's import sorter (I) rules.
| Argument / option | Default | Description |
|---|---|---|
--write |
off | Apply import sorting to disk. |
core code lint
core code lint
Check code quality using Black and Ruff (Read-Only).
core code logging
core code logging [OPTIONS]
Standardize logging across the codebase.
Replaces print() statements and malformed f-strings in loggers with constitutional standard logging (LOG-001/LOG-003).
| Argument / option | Default | Description |
|---|---|---|
--write |
off | Convert print() to logger calls. |
core code test
core code test
Run the project test suite via pytest.
core code verify
core code verify [OPTIONS]
Verify the current codebase against a previously created baseline. Detects any unauthorized MODIFICATIONS, DELETIONS, or NEW files.
| Argument / option | Default | Description |
|---|---|---|
--label, -l |
default |
Baseline label to verify against. |
core lane
Assisted Remediation Lane: work delegated findings under human-gated approval.
core lane claim
core lane claim FINDING_ID [OPTIONS]
Mark a delegated finding as being worked, so it is tracked, not parked.
Claiming does not change the finding's status — it stays a live lane item — it only records who is working it (ADR-109 §2).
| Argument / option | Default | Description |
|---|---|---|
FINDING_ID |
required | Delegated finding id (from lane list/lane next). |
--agent, -a |
claude-code |
Identity of the working agent. |
core lane list
core lane list [OPTIONS]
List delegated findings awaiting assisted remediation (indeterminate + human).
| Argument / option | Default | Description |
|---|---|---|
--limit, -n |
20 |
Max delegated findings to show. |
--full-ids, -f |
off | Show full finding IDs instead of truncating. |
core lane next
core lane next
Show the oldest delegated finding (the FIFO head of the lane) with detail.
The agent's "pull next work" surface. The rich context bundle (related files, guidance, rule text) is the deferred #653 exporter; for now this surfaces the finding's own payload so you know what to work next.
core lane propose
core lane propose FINDING_ID [OPTIONS]
Validate an agent-authored diff and, if it clears, submit it for approval.
Flow (ADR-109): read the finding's rule, run assisted.validate_diff
against the diff in a throwaway worktree (apply + ruff + the offending rule
must no longer fire + mapped tests), and only on a clean verdict create the
human-gated proposal and move the finding out of the inbox into "being
worked". A diff that fails validation never reaches the approval queue.
| Argument / option | Default | Description |
|---|---|---|
FINDING_ID |
required | Delegated finding id (from lane list). |
--patch, -p |
required | Path to the unified diff the agent produced for this finding. |
core project
Bring a repository under governance: scout, onboard, promote (BYOR).
core project onboard
core project onboard PATH [OPTIONS]
Onboard an existing repository into CORE governance — Phase A (BYOR).
Delivers the machinery floor (META schemas, taxonomies, constitution stub,
enforcement/config) into the target's .intent/. No rules are included; run
project scout afterwards to induce and ratify rules for this repo (ADR-119).
Dry-run by default; pass --write to apply.
Pass --write --stage to write to work/staged/<name>/ first, inspect the
files, then run project onboard promote <path> to deliver to the target.
| Argument / option | Default | Description |
|---|---|---|
PATH |
required | Path to existing repository. |
--write |
off | Write .intent/ directory to the target path. |
--stage |
off | Write to work/staged/<name>/ for inspection before promoting (ADR-123). Requires --write; ignored in dry-run mode. |
core project promote
core project promote PATH
Promote a staged machinery floor into the target repository (ADR-123).
Reads from work/staged/<name>/.intent/ (within CORE's repo) and writes to
<path>/.intent/. Run project onboard promote --help for full lifecycle details.
| Argument / option | Default | Description |
|---|---|---|
PATH |
required | Target repository path (same path used with --stage). |
core project scout
core project scout PATH [OPTIONS]
Induce and ratify governance rules for a repository — Phase B (BYOR Scout).
Calls the CORE API to extract signals and propose candidate rules
(LLM-assisted; falls back to a universal menu when LLM is unavailable).
Walks you through per-rule ratification. Only confirmed rules are written
(ADR-119 D5 — no --accept-all). Requires Phase A first:
run project onboard <target> --write before this command.
| Argument / option | Default | Description |
|---|---|---|
PATH |
required | Path to the target repository. |
--write |
off | Write inducted rules to .intent/ after ratification. |
--reset |
off | Clear existing scout_inducted.json and re-run induction. |
core proposals
Operations for the A3 Autonomous Proposal system (propose, approve, execute).
core proposals approve
core proposals approve PROPOSAL_ID [OPTIONS]
Authorize a pending proposal for execution.
Shows the proposal and its review, then asks the person at the terminal to type the proposal's short id. Refused without a terminal.
| Argument / option | Default | Description |
|---|---|---|
PROPOSAL_ID |
required | |
--by |
cli_admin |
Approver identity. |
--authority |
principal.governor |
Authority under which approval is granted (URS NFR.5). |
core proposals create
core proposals create GOAL [OPTIONS]
Create a new autonomous proposal for system modification.
Validates the plan and performs an initial risk assessment.
| Argument / option | Default | Description |
|---|---|---|
GOAL |
required | Strategic goal of the proposal. |
--action, -a |
Format: action_id:param=value | |
--file, -f |
Specific files affected. | |
--write |
off | Persist the proposal. Dry-run by default. |
core proposals execute
core proposals execute PROPOSAL_ID [OPTIONS]
Execute an approved proposal.
Runs the atomic action sequence defined in the proposal.
| Argument / option | Default | Description |
|---|---|---|
PROPOSAL_ID |
required | |
--write |
off | Apply changes to the system. |
core proposals integrate
core proposals integrate [OPTIONS]
Integrate staged changes into the governed repository and commit them.
| Argument / option | Default | Description |
|---|---|---|
-m, --message |
required | The git commit message for this integration. |
--write |
off | Commit and integrate staged changes (default: dry-run). |
core proposals list
core proposals list [OPTIONS]
List recent autonomous proposals and their risk assessments.
| Argument / option | Default | Description |
|---|---|---|
--status, -s |
Filter by status (pending, approved, etc.) | |
--limit, -n |
20 |
Max results. |
--full-ids, -f |
off | Show complete proposal IDs instead of truncating. |
core proposals reject
core proposals reject PROPOSAL_ID [OPTIONS]
Reject a proposal and prevent its execution.
Revival of deferred findings (ADR-010 §7a / ADR-045) now happens on the API side; this command only renders the result.
| Argument / option | Default | Description |
|---|---|---|
PROPOSAL_ID |
required | |
--reason, -r |
required |
core proposals show
core proposals show PROPOSAL_ID
Show detailed breakdown and risk assessment of a proposal.
| Argument / option | Default | Description |
|---|---|---|
PROPOSAL_ID |
required |
core symbols
Operations for the symbol registry and Knowledge Graph identification.
core symbols audit
core symbols audit
Audit symbol integrity: drift summary and unassigned ID report.
core symbols fix-ids
core symbols fix-ids [OPTIONS]
Assign stable '# ID:' anchors to all untagged public symbols.
Scans 'src/' and modifies files to ensure knowledge graph stability. Pass --write to apply changes (default is dry-run).
| Argument / option | Default | Description |
|---|---|---|
--write |
off | Inject missing UUIDs into source files. |
core symbols resolve-duplicates
core symbols resolve-duplicates [OPTIONS]
Find and resolve duplicate '# ID:' anchors in the codebase.
The older entry is preserved; colliding symbols receive fresh identifiers. Pass --write to apply changes (default is dry-run).
| Argument / option | Default | Description |
|---|---|---|
--write |
off | Regenerate conflicting UUIDs. |
core vectors
Semantic search over the governed repository's vector index.
core vectors query
core vectors query QUERY [OPTIONS]
Semantic search in vector collections.
Search constitutional documents using natural language queries.
Examples: core vectors query "file access rules" core vectors query "atomic actions" --collection patterns --limit 3
| Argument / option | Default | Description |
|---|---|---|
QUERY |
required | Natural language query |
--collection, -c |
policies |
Collection to query: 'policies', 'patterns', 'specs', or 'code' |
--limit, -n |
5 |
Max results to return |