CLI

stoa scan [PATH]            # scan a repository (report-only by default)
stoa diff BASE HEAD         # diff agent reach between two registries
stoa graph [REGISTRY]       # render the architecture graph (Mermaid)
stoa export --assurance     # export the 18-area assurance packet
stoa approve ...            # record an intentional drift approval
stoa runtime analyze DIR    # summarize observed behavior from local traces
stoa runtime baseline DIR   # behavioral baseline (commit it, like approvals)
stoa runtime drift DIR      # compare live behavior to the baseline
stoa runtime merge DIR      # enrich a registry with runtime evidence
stoa init github            # scaffold the CI workflow
stoa init declarations      # stub stoa-declared.toml from the last scan
stoa init runtime           # scaffold [runtime] config + SDK example

stoa scan

--html PATH / --json PATH        report + registry output paths
--sarif PATH                     SARIF 2.1.0 with stoa-dim:* tags
--base GIT_REF                   diff-aware gating (added lines only)
--fail-on {none,high,critical}   gate on all findings at/above a severity
--fail-on-new {none,high,critical}
--strict                         fail on high-confidence criticals, and
                                  escalate stoa-declared.toml warnings to errors
--no-ast                         disable the AST layer + flow-based AI rules
--no-dimensions                  skip the dimension assessment + matrix
--no-graph                       skip the architecture graph in the HTML report
--taxonomy PATH                  custom dimension taxonomy
--diff-against GIT_REF           scan, then diff reach against a ref
--fail-on-drift {none,low,medium,high}
--fail-on-dimension-increase DIM=LEVEL
--github-annotations / --summary-file PATH
--include / --exclude / --no-git / --verbose / --quiet

Exit codes

stoa diff and stoa approve

See Capability drift.

stoa runtime and stoa scan --with-runtime

stoa runtime analyze TRACES_DIR [--registry PATH] [--out stoa-runtime.json]
stoa runtime map     TRACES_DIR --registry PATH
stoa runtime baseline TRACES_DIR [--out .stoa/baseline.json]
stoa runtime drift   TRACES_DIR [--baseline PATH] [--registry PATH]
                     [--fail-on-drift {info,medium,high}] [--out PATH] [--config PATH]
stoa runtime merge   TRACES_DIR --registry PATH [--out PATH | --in-place] [--config PATH]
stoa scan . --with-runtime TRACES_DIR    # scan + enrich in one pass

Shadow mode: everything is report-only unless --fail-on-drift is passed (then stoa diff exit-code conventions apply). Traces are local stoa-trace/1.0 JSONL written by the stoa.runtime SDK — see the Runtime overlay workflow.

stoa graph

[REGISTRY]                       existing stoa-registry.json (omit: scan the worktree)
--format mermaid                 output format (default, only option today)
--out PATH                       write to PATH (default: stdout)
--focus AGENT_ID                 render only that node + its direct neighbors

See Architecture graph.

stoa export --assurance

[REGISTRY]                       existing stoa-registry.json (omit: scan the worktree)
--assurance                      required -- the only export kind today
--format {json,md}               output format (default: md)
--out PATH                       write to PATH (default: stdout)

See Assurance export.

stoa init declarations

stoa init declarations [--registry PATH] [--force]

Stubs stoa-declared.toml with every real scanned agent id. Requires a prior stoa scan (reads stoa-registry.json by default) -- prints a clear message if none is found rather than emitting an empty, useless stub.

See Declarations.