CLI reference

Everything is driven by the orchestrator CLI — 55 commands across 7 areas. This page covers the most-used commands; run orchestrator <command> --help for the authoritative, up-to-date options. If this page and --help ever disagree, --help is right.

Repo-analysis commands accept a local path or a git URL, and default to ..

Understand a codebase — the Knowledge Graph

Extract and read the Product Knowledge Graph (PKG). Deterministic, no LLM.

orchestrator understand .            # extract & query the graph
orchestrator understand . --check    # verify episteme/ still matches the code (CI)

Command	What it does
`orchestrator understand .`	extract the PKG and name the files to read first
`orchestrator state .`	team-facing snapshot: health, coverage, top doc drift
`orchestrator profile .`	languages, framework, DB, tests, task type
`orchestrator pkg export .`	write the graph out (nodes + edges)
`orchestrator pkg accuracy .`	precision/recall against the fixture corpus

Deterministic report

There is no --report flag. A byte-stable report comes from state with --out and --no-timestamp:

orchestrator state . --out report.html --no-timestamp

The extension picks the format (.html → a self-contained shareable report; anything else → markdown). With --no-timestamp, two runs of the same commit produce identical bytes — diff it or check it into CI like any other artifact.

Grounded design, debugging & RCA

KG-grounded engineering commands, anchored to real code. Deterministic by default.

Command	What it does
`orchestrator design .`	spec × graph → a design annotated with its blast radius
`orchestrator investigate . --source jira://PROJ-123`	where a ticket lands in the code, before you design
`orchestrator localize . --trace trace.txt`	map a stack trace to the symbols it names
`orchestrator rca . --text "sessions expire early"`	fault site + ranked root-cause hypotheses + fix approach
`orchestrator regression . --symbol validate`	blast radius split into covered vs. untested reachable code
`orchestrator audit .`	read-only agentic auditor → findings report (needs an LLM provider)

regression takes --symbol <name> (the symbol you’re about to change) or --trace <file> (the fault site) — not a positional argument. rca reads the bug from --source, --trace, or --text.

The SDLC pipeline — build features (gated)

Requirements → code → tests → reviewed PR, with human gates. --safe is the default and writes nothing external; pass --live to push and open a real PR.

# One intent, end to end — feed it a spec source
orchestrator sdlc feature --source file://./spec.md

# One ticket, all the way through: research → design → gate → code → tests → PR
orchestrator sdlc autorun --source jira://PROJ-14 --issue PROJ-14 --path . --safe --max-cost 10

✓ branch feature/validate-guard
  3 files · +148 −12 · 6 tests added
⏸ no push, no PR — awaiting your approval

sdlc autorun refuses to start without an approved build document — run orchestrator sdlc plan then orchestrator sdlc approve first. Both stop at the two governance gates; nothing is pushed or merged under --safe.

Requirements intake, MCP & registry

Command	What it does
`orchestrator ingest --source confluence://<id>`	source → intents → specs → backlog
`orchestrator backlog`	review the derived backlog
`orchestrator mcp list`	onboarded MCP servers (governed, audited)
`orchestrator mcp ingest-docs`	pull a repo’s Confluence/Jira/RAG doc sources (declared under `docs:` in `.spine/repos.yaml`) into `blast_radius`, `explain_symbol` and `docs_for`
`orchestrator template list` · `orchestrator contract list`	reusable capability templates & API contracts