CLI Surface

The nimicoding CLI is a small, bounded set of commands. The package is intentionally boundary-complete, not run-complete: the CLI bootstraps, validates, and projects, but it does not autonomously execute packets.

For per-command field-level reference see Reference → CLI Commands.

Command Categories

The CLI's verbs fall into a small number of categories:

Category	Commands
Bootstrap	start, clear, doctor
Topic lifecycle	topic create, topic wave ..., topic packet freeze, topic worker dispatch, topic result record, topic closeout ..., topic true-close-audit
Topic runner	topic run-next-step, topic-runner step, topic-runner run
Sweep audit	sweep audit plan, sweep audit chunk ..., sweep audit ledger build, sweep audit remediation-map build, sweep audit closeout summary, sweep audit status
Sweep design	sweep design intake, sweep design packet-build, sweep design packet-build-batch, sweep design auditor-prompt, sweep design result-ingest, sweep design ledger-validate, sweep design finalize, sweep design wave-plan
Skill handoff	handoff, closeout
High-risk execution	admit-high-risk-decision, ingest-high-risk-execution, review-high-risk-execution, decide-high-risk-execution
Mechanical validators	per-artifact validators for execution-packet, orchestration-state, prompt, worker-output, acceptance
Spec audit	validate-spec-tree, validate-spec-audit, blueprint-audit
Repo gates	pnpm check:spec-authority-cutover-readiness (via the host repo's tooling)

Each is bounded; new verbs require admitted contract extensions.

Bootstrap

nimicoding start

Detect project state, project package source into host paths, seed .nimi/**, prepare one authoritative JSON AI task package, print a paste-ready prompt.

Property	Value
Mode	Interactive: explain → confirm → apply, one step at a time
Failure	Fail closed on unknown CLI options
Preserves	Existing truth files (does not overwrite)
Refuses	Unsupported bootstrap contract versions

nimicoding clear

Remove only managed AI blocks in AGENTS.md and CLAUDE.md, remove only package-owned bootstrap files when they exactly match the seed.

Property	Value
Preserves	Project-owned truth, locally modified bootstrap files, .nimi/spec/**, .nimi/local/**, .nimi/cache/**
Refuses	Implicit deletion of project-owned truth or local artifacts

nimicoding doctor

Validate .nimi/** bootstrap seed presence, contract compatibility, lifecycle markers, cross-contract reference alignment, host-adapter boundary truth, named-overlay status, admitted package-owned adapter profile overlays, and more.

| Output | Human-readable or --json | | Failure | Fail closed when lifecycle, canonical tree, and auditability drift apart |

Topic Lifecycle

The topic command family manages topic folders under .nimi/topics/{proposal,ongoing,pending,closed}/. It creates topics, adds and selects waves, admits waves, freezes packets, dispatches worker or audit packets, records typed results, handles remediation and overflow, and closes waves or topics.

The mechanical runner entrypoint is:

nimicoding topic run-next-step <topic-id> --json

For repeated execution, use topic-runner step or topic-runner run with an explicit run id and adapter. Packet ids should include the wave identity, such as wave-1-add-reference-field, so the generated packet-*.md artifact remains unambiguous in the topic folder.

Sweep Audit

The sweep audit command family splits a target root into auditable chunks, dispatches chunks, ingests auditor evidence, records manager review, builds immutable ledgers, and projects remediation maps or closeout summaries.

Plan output reports chunk artifact refs. The chunk ids are stored in those chunk files and follow the chunk-001 style generated by the planner.

Sweep Design

The sweep design command family starts after a sweep has findings. It reads .nimi/local/audit/evidence/<sweep-id>/findings.yaml, forks those findings into .nimi/local/sweep-design/<run-id>/, and turns raw audit output into planning artifacts that can become topic waves.

It does not edit the original findings. It asks Codex or another host to inspect bounded finding packets, return typed design-auditor results, append revision-ledger entries, validate the ledger, finalize local-only design state, and build a non-mutating wave plan. Result ingest can accept focused or all-mode auditor output, but worker dispatch remains disallowed until a topic wave is separately admitted.

Phase	Role
intake	Fork audit findings into a design workset
packet-build	Build a design-auditor packet for one or more findings
packet-build-batch	Build a manifest of design-auditor packets
auditor-prompt	Emit the prompt and required result shape for a packet
result-ingest	Ingest a typed design-auditor result and append revisions
ledger-validate	Validate revision-ledger and final-outcome provenance
finalize	Emit the local-only final state report
wave-plan	Emit candidate topic commands without mutating topic state

Skill Handoff

nimicoding handoff --skill <skill-id> --json

Export a machine-readable external-handoff payload. With --prompt, also print a human-readable host briefing.

Property	Value
Skill	Required (spec_reconstruction / doc_spec_audit / audit_sweep / high_risk_execution)
Output	Authoritative JSON payload
Host posture	Vendor-neutral; supports any admitted host (Claude, Codex, Gemini, OMX, etc.)
Refuses	doc_spec_audit and high_risk_execution until canonical tree is ready

nimicoding closeout --skill --outcome --verified-at

Project external skill results into a local-only closeout payload. Optionally --write-local under .nimi/local/handoff-results/.

Property	Value
Validation	Closeout result must pass typed contract
Failure	Fail closed if outcome contradicts canonical-tree state, if refs escape declared local artifact roots, etc.
Local-only	Never promotes to project semantic truth

High-Risk Execution

nimicoding admit-high-risk-decision --from <json> --admitted-at <iso8601>

Accept only nimicoding.high-risk-decision.v1 payloads with decisionStatus: manager_decision_recorded. Project canonical admission preview. Write tracked semantic truth only with explicit --write-spec.

nimicoding ingest-high-risk-execution --from <json>

Accept only high_risk_execution closeout artifacts with outcome: completed and summary.status: candidate_ready. Mechanically validate referenced artifacts; project local-only ingest payload.

nimicoding review-high-risk-execution --from <json>

Accept ingest payloads with ok: true. Project review-ready attachment for manager-owned review. Carry attachment refs and ingest validation evidence.

nimicoding decide-high-risk-execution --from <json> --acceptance <path> --verified-at <iso8601>

Accept review payloads with ok: true and reviewStatus: ready_for_manager_review. Mechanically validate acceptance artifact. Require Disposition: line. Project local-only manager decision.

Mechanical Validators

Per-artifact validators emit machine-readable validator-cli-result.v1 JSON.

Validator	Validates
execution-packet	Frozen packet shape
orchestration-state	Orchestration state record
prompt	Prompt payload
worker-output	Worker output shape
acceptance	Acceptance evidence

Property	Value
Path required	Yes
Output	JSON on success or refusal
Failure	Fail closed on missing required sections, malformed YAML, or seed-contract drift

Spec Audit

nimicoding validate-spec-tree

Validate canonical tree structure under .nimi/spec.

nimicoding validate-spec-audit

Validate per-file grounding, inference, and unresolved-gap tracking under .nimi/spec/_meta/spec-generation-audit.yaml.

nimicoding blueprint-audit

Compare a repo-local blueprint root with the candidate canonical tree under .nimi/spec. Explicit equivalence audit; does not perform routing changes.

Reader Scenario: A First-Run Bootstrap

You install Nimi Coding in a project for the first time.

nimicoding start

The CLI walks you through:

1. Detect project state.
2. Confirm or accept managed AI entrypoints (AGENTS.md, CLAUDE.md blocks).
3. Seed .nimi/** with package-owned source.
4. Prepare one authoritative JSON AI task package for spec_reconstruction.
5. Print a paste-ready prompt for the AI host of your choice.

You hand the prompt to your AI host; the host runs reconstruction; you return the result via nimicoding closeout.

Reader Scenario: A High-Risk Execution Cycle

You have a mature project with canonical spec; you want to run substantive AI-coding work.

Step	Command
1. Manager admits a packet	(manual; topic.yaml + packet artifact)
2. Pre-implementation audit (if needed)	(host runs audit; result recorded)
3. Hand off to host	nimicoding handoff --skill high_risk_execution --json
4. Host executes; returns result	(host-side)
5. Ingest result	nimicoding ingest-high-risk-execution --from result.json
6. Review	nimicoding review-high-risk-execution --from ingest.json
7. Manager decision	nimicoding decide-high-risk-execution --from review.json --acceptance accept.md --verified-at ...
8. Closeout	(manual; closeout artifact)

Each step is bounded by the CLI's typed validation. Skipping a step or smuggling fields through means the CLI refuses.

What The CLI Does Not Do

Concern	Why not
Autonomous packet execution	Host AI owns execution
Provider invocation	Package does not call AI providers
Scheduler	Scheduling is a host concern
Notification	UX is host concern
Self-update	Out of standalone scope

These are explicitly deferred surfaces.

Source Basis

• nimi-coding/README.md (CLI section)
• nimi-coding/cli/ (CLI implementation)
• nimi-coding/contracts/topic.schema.yaml
• nimi-coding/contracts/audit-plan.schema.yaml
• nimi-coding/contracts/sweep-design-result.yaml
• nimi-coding/methodology/skill-handoff.yaml
• nimi-coding/methodology/skill-installer-result.yaml
• nimi-coding/contracts/execution-packet.schema.yaml
• nimi-coding/contracts/orchestration-state.schema.yaml
• nimi-coding/contracts/prompt.schema.yaml
• nimi-coding/contracts/worker-output.schema.yaml
• nimi-coding/contracts/acceptance.schema.yaml