CLI Reference¶

The executable command tree is the authority for command availability. This page is mechanically checked against src/ArchLinterNet.Cli/Commands: if a command is added or removed without updating the markers below, make lint-docs fails.

Run arch-linter-net --help or arch-linter-net <command> --help for the exact options accepted by the installed tool.

Command map¶

Command	Purpose

| arch-linter-net [options] | Normal architecture validation. |

| arch-linter-net badge | Badge payload workflows. |

| arch-linter-net badge architecture-policy --input <strict-result.json> | Project an existing strict JSON result to a Shields endpoint payload; does not rerun analysis. |

| arch-linter-net badge architecture-health --input <architecture-health.json> [--output <badge.json>] | Project canonical Architecture Health plus policy inventory into a Shields endpoint payload; does not rerun analysis. |

| arch-linter-net badge architecture-health doctor --input <badge-relay-config.json> [--public] | Diagnose setup compatibility, evidence availability, expiry, and disclosure-safe remediation. |

| arch-linter-net badge architecture-health apply-handoff --input <bootstrap-handoff.json> --output <repository-directory> --expected-base-sha <sha> --expected-base-tree-sha <tree-sha> --repository <owner/name> --repository-id <id> --repository-owner-id <id> | Verify a private trusted bootstrap handoff against an exact local review branch, then atomically apply only its managed setup files. |

| arch-linter-net baseline | Migration-baseline lifecycle. |

| arch-linter-net baseline generate ... | Capture current violations into a reviewed baseline. |

| arch-linter-net baseline migrate ... | Migrate supported baseline formats/identity. |

| arch-linter-net baseline update ... | Refresh a baseline from current findings under the requested policy. |

| arch-linter-net baseline prune ... | Remove baseline entries that are no longer current. |

| arch-linter-net baseline diff ... | Compare current findings with a baseline. |

| arch-linter-net baseline verify ... | Verify baseline integrity/current applicability. |

| arch-linter-net cache | Persistent analysis-cache operations. |

| arch-linter-net cache inspect --cache <auto|path> | Inspect the selected cache. |

| arch-linter-net cache clear --cache <auto|path> | Clear the selected cache with containment checks. |

| arch-linter-net change | Complete architecture change snapshots/reports. |

| arch-linter-net change snapshot --policy <path> --output <path> | Write a complete architecture change snapshot; use build-state options when a consumer requires post-build analysis. |

| arch-linter-net change report --base <path> --current <path> --execution-context <id> | Compare two architecture snapshots into a correlatable report artifact. |

| arch-linter-net coverage | Architecture coverage artifact utilities. |

| arch-linter-net coverage report --input <validation.json> ... | Render a Markdown coverage report from strict validation JSON. |

| arch-linter-net coverage extract --input <combined.json> --mode <mode> --output <path> | Extract one validation mode from combined JSON. |

| arch-linter-net explain --source <id> --target <id> ... | Explain a dependency path at namespace/type granularity. |

| arch-linter-net gate ... | Fail CI on new architecture debt and error-severity policy weakening. |

| arch-linter-net health ... | Project the canonical non-compensating architecture-health/v1 summary, including bound external evidence when configured. |

| arch-linter-net health revalidate-publication --input <architecture-health.json> --evaluation-date <yyyy-MM-dd> ... | Refresh only the product-owned temporal publication receipt for unchanged serialized Health evidence; does not rerun analysis. |

| arch-linter-net graph ... | Export dependency graphs as JSON, DOT, or Mermaid at supported granularities. |

| arch-linter-net measure ... | Read-only, deterministic report of declared architecture metrics. |

| arch-linter-net history | Architecture history forensics. |

| arch-linter-net history analyze ... | Analyze architecture evidence/history for the requested repository range. |

| arch-linter-net policy | Policy-only inspection/review workflows. |

| arch-linter-net policy check --policy <path> | Validate policy/static configuration without claiming architecture compliance. |

| arch-linter-net policy context --policy <path> --format <json|markdown> | Export effective policy facts for humans/agents. |

| arch-linter-net policy weakening --base-context <path> --current-context <path> [--public-api-approval <path>] | Compare exported contexts for typed policy relaxations, with optional exact reviewed public-API addition approval. |

| arch-linter-net public-api | Public API snapshot lifecycle. |

| arch-linter-net public-api capture ... | Capture a reviewed public API snapshot. |

| arch-linter-net public-api diff ... | Compare public API snapshots/current surface. |

| arch-linter-net public-api migrate ... | Migrate supported snapshot grammar/identity. |

| arch-linter-net public-api update ... | Update a reviewed public API snapshot. |

| arch-linter-net report | Render reports from canonical local architecture artifacts. |

| arch-linter-net report pr --health <architecture-health.json> --change <architecture-change.json> | Render a deterministic architecture-only pull-request Markdown report from canonical artifacts; does not rerun analysis or call GitHub. |

| arch-linter-net topology | Capture, compare, and verify declared architecture topology. |

| arch-linter-net topology capture ... | Capture canonical observed topology as a review artifact. |

| arch-linter-net topology diff ... | Compare declared topology with ordinary validation evidence. |

| arch-linter-net topology verify ... | Verify declared topology with ordinary validation semantics. |

| arch-linter-net scaffold | Repository-development scaffolding. |

| arch-linter-net scaffold cli-command --module <name> --command <name> ... | Scaffold a CLI command module in this codebase. |

| arch-linter-net schema | Installed schema-registry discovery. |

| arch-linter-net schema list | List packaged logical schemas. |

| arch-linter-net schema print <logical-id> | Print one packaged schema for offline tooling/editors. |

Normal validation¶

arch-linter-net \
  --policy architecture/arch.yml \
  --mode strict \
  --ensure-built

The CLI compatibility default for --policy is architecture/dependencies.arch.yml. The documentation uses architecture/arch.yml as a concise recommended convention, so examples pass it explicitly.

Core validation options¶

Option	Meaning
`-p, --policy <path>`	Selected root policy.
`-m, --mode <strict\|audit>`	Validation mode; default is strict.
`--strict` / `--audit`	Mode shortcuts.
`--contract <id>`	Restrict execution to a contract ID; repeat where supported.
`--condition-set <name>`	Select a configured preprocessor symbol set for source analysis.
`--baseline <path>`	Merge reviewed baseline identities with policy ignores.
`--ensure-built`	Explicitly build the selected project graph once, verify its build receipt, then validate.
`--no-restore`	In ensure-built mode, fail closed if restore is required.
`--configuration <name>`	Build-state configuration selector.
`--framework <tfm>`	Target-framework selector.
`--platform <name>`	Platform selector.
`--runtime <rid>`	Runtime identifier selector.
`--max-parallelism <n>`	Bound parallel assembly/fact scanning; `1` is supported sequential execution.
`--waiver-evaluation-date <yyyy-MM-dd>`	Use a fixed UTC calendar date for waiver expiry evaluation.
`--cache <auto\|path>`	Opt into persistent analysis-cache/v1; disabled by default.
`--timings`	Print phase timing information to stderr.
`--profile <stdout\|stderr\|path>`	Emit analysis-profile/v1 JSON independently from normal reports.
`-f, --format <human\|json\|sarif>`	Primary stdout format.
`--json`	Shortcut for JSON stdout.
`--report <format=destination>`	Add repeatable human/JSON/SARIF sinks to stdout, stderr, or a file.
`-h, --help`	Help.
`-v, --version`	Tool version.

Exit codes for normal validation are 0 passed, 1 architecture/policy findings failed the run, and 2 runtime/argument/input error. See Exit codes for command-specific details.

Build-state behavior¶

--ensure-built is never implicit. It exists to make build provenance explicit and reproducible; normal validation can consume already-built outputs.

The Apple Silicon self-dogfood failure tracked in #639 is fixed on current main by #648. Evergreen docs describe the fixed behavior. If reproducing an older release artifact, use the release-provenance workflow instead of assuming the historical defect still exists.

Policy review workflow¶

Static policy validation:

arch-linter-net policy check --policy architecture/arch.yml

Effective policy facts:

arch-linter-net policy context \
  --policy architecture/arch.yml \
  --format json > current-policy.json

Base/current weakening review:

arch-linter-net policy weakening \
  --base-context base-policy.json \
  --current-context current-policy.json \
  --public-api-approval reviewed-api-additions.json

policy weakening compares exported contexts. It is a bounded change-time guardrail, not a second architecture evaluator; impact_not_proven means review is required.

--public-api-approval is optional and fail-closed. Its JSON root is an array of approvals; each approval binds schema_version: 1, kind: "architecture-public-api-addition-approval", the exact base/current context digests, a public_api_surface contract id, and the complete added snapshot entries. When approvals are supplied, policy weakening captures the current CLR API from --policy and requires it to match the current reviewed snapshot. The approval is accepted only for an unchanged exact or additions_only contract whose canonical base-snapshot-to-live-CLR delta has precisely those additions and no removals or signature changes. It cannot approve selector, inventory, or comparison-mode changes.

Baseline workflow¶

Capture current debt:

arch-linter-net baseline generate \
  --config architecture/arch.yml \
  --output architecture/baseline.arch.yml \
  --reason "Reviewed adoption baseline"

Use update, prune, diff, and verify during normal maintenance. Use migrate when moving supported baseline identity/format forward. See Migration baselines.

No-new-debt gate¶

arch-linter-net gate \
  --policy architecture/arch.yml \
  --baseline architecture/baseline.arch.yml \
  --mode all \
  --ensure-built

gate can also consume exported base/current policy contexts and the same optional --public-api-approval artifact, so CI catches both new findings and error-severity policy weakening without bypassing reviewed public-API changes.

Architecture health¶

arch-linter-net health \
  --policy architecture/arch.yml \
  --baseline architecture/baseline.arch.yml \
  --mode all \
  --format json \
  --execution-context pr-123

health is a read-only projection of canonical architecture-governance authorities. It reports the ordered architecture-health/v1 dimensions and their reasons in human or JSON output. The projection is non-compensating: it has no score, percentage, letter grade, badge, pull-request rendering, or SARIF output. A valid but unassessable result is emitted as a health document rather than a command-error document.

For each policy-declared external_evidence requirement, pass one repository-local SARIF binding: --external-evidence id=<id>,path=<path>. Add repository=<value>, revision=<value>, and scope=<value> to a binding when that artifact's producer context is supplied outside SARIF. The current assessment context is explicit and shared by the bindings: use --evidence-repository, --evidence-revision, and --evidence-scope. Health uses the same canonical binding authority as validation before it writes its reporting evidence.

For topology, metric budgets, and imported external diagnostics, evaluable means only that the authority could assess the control; the health dimension still reflects that authority's resulting strict finding or clean receipt. Each reason retains canonical family, control, policy, and evidence references so automation can drill into the source receipt. A stale or otherwise blocking waiver lifecycle record remains a failing lifecycle result; a resolved baseline entry remains visible as baseline hygiene but is not classified as new architecture debt.

Coverage retains its existing severity semantics in Health: analysis.coverage: error is failing, while warn remains non-blocking reportable evidence. For --mode audit and --mode all, audit_evidence preserves audit-only diagnostics without turning the Health gate into a strict failure.

Architecture pull-request report¶

Render a reviewer-oriented Markdown report from a canonical Health artifact and a canonical architecture-change report:

arch-linter-net report pr \
  --health architecture-health.json \
  --change architecture-change.json \
  --output architecture-pr-report.md \
  --max-details 20

--output is optional; without it, Markdown is written to standard output. --max-details is optional and must be a positive count. It bounds each detailed evidence section independently while retaining canonical totals and making omitted details explicit. The report is deterministic and architecture-only: it reads the supplied artifacts, does not run or recreate analysis, and does not inspect or call GitHub.

The Health input must be an architecture-health/v1 document from a supported CLI. When it includes versioned canonical reporting evidence, its non-empty execution context must match the versioned canonical architecture-change JSON report's context and selected mode receipt; mismatches are rejected. A legacy Health artifact without the reporting-evidence envelope still renders a report, but all evidence drill-down is explicitly unavailable; it is never presented as zero or pass. The command does not reopen snapshots or compare them again.

Create the pair from the real producers using one workflow-owned identifier:

# Base and candidate checkouts/worktrees, respectively
arch-linter-net change snapshot --policy architecture/arch.yml --mode strict --output base-snapshot.json
arch-linter-net change snapshot --policy architecture/arch.yml --mode strict --output current-snapshot.json

arch-linter-net change report \
  --base base-snapshot.json \
  --current current-snapshot.json \
  --execution-context pr-123 \
  --format json \
  --output architecture-change.json

arch-linter-net health \
  --policy architecture/arch.yml \
  --baseline architecture/baseline.arch.yml \
  --mode strict \
  --format json \
  --execution-context pr-123 \
  > architecture-health.json

If that policy declares required external evidence, add the producer inputs to the same Health invocation, for example:

arch-linter-net health \
  --policy architecture/arch.yml \
  --baseline architecture/baseline.arch.yml \
  --mode strict \
  --format json \
  --execution-context pr-123 \
  --external-evidence id=security-scan,path=artifacts/security.sarif \
  --evidence-repository example/repository \
  --evidence-revision "$GIT_COMMIT" \
  --evidence-scope pull-request \
  > architecture-health.json

The report headline repeats direct Health/projection facts such as gate and health; it is not a score, percentage, grade, or compensating quality calculation. Rule/effective-control counts, applicability completeness, topology evidence, and external evidence remain separate sections and must not be combined or inferred from one another. For each configured external evidence artifact, the report retains its logical identity and canonical trust receipt: current, stale, or wrong_context as applicable, plus the selected run/result provenance. A valid evidence run with zero findings is shown as current with results=0. Missing or incomplete canonical evidence is rendered as unavailable or unassessable, never as zero or pass. Canonical identities and provenance are retained where supplied so reviewers can drill back to the source artifacts.

This command only renders the local report. GitHub comment publication, workflow/event orchestration, security permissions, and related integration remain outside this command's boundary. The repository's separate completed-CI publisher consumes the rendered file after transport validation; the command itself never calls GitHub.

Change snapshots¶

arch-linter-net change snapshot \
  --policy architecture/arch.yml \
  --mode strict \
  --ensure-built --configuration Debug --framework net10.0 \
  --output base-snapshot.json

arch-linter-net change snapshot \
  --policy architecture/arch.yml \
  --mode strict \
  --ensure-built --configuration Debug --framework net10.0 \
  --output current-snapshot.json

arch-linter-net change report \
  --base base-snapshot.json \
  --current current-snapshot.json \
  --execution-context local-review \
  --format human

When the policy opts into a shared framework, use --ensure-built for both snapshots and keep --configuration, --framework, --platform, and --runtime consistent across them. --no-restore preserves an offline, fail-closed build when the consumer has already restored its prerequisites.

Snapshots are architecture evidence; reports compare two complete snapshots rather than reparsing arbitrary prose.

Coverage artifacts¶

Contract coverage runs during validation. The coverage command family post-processes validation JSON:

arch-linter-net coverage report \
  --input architecture-strict.json \
  --changed-files changed-files.txt \
  --repo-root . \
  --output architecture-coverage.md

Implemented policy coverage scopes are documented in Coverage contracts.

Dependency investigation¶

Export a graph:

arch-linter-net graph \
  --policy architecture/arch.yml \
  --mode all \
  --level namespace \
  --format mermaid

Explain a path:

arch-linter-net explain \
  --policy architecture/arch.yml \
  --source MyApp.Application \
  --target MyApp.Infrastructure \
  --level namespace

explain supports namespace/type granularity. For assembly-level topology, use graph --level assembly.

Use history analyze when the question is how architecture evidence changed over repository history rather than how the current graph is connected.

Public API¶

The public-api command family supports capture, diff, update, and migration of reviewed public API snapshots used by public API surface contracts. See Public API surface contracts.

Topology review¶

The topology command family captures observed facts for review, projects declared-versus-observed drift, and invokes ordinary validation with a focused entry point. It never writes a reviewed topology declaration. See Review a topology before declaring it.

Cache¶

Persistent analysis cache is opt-in:

arch-linter-net cache inspect --cache auto
arch-linter-net cache clear --cache auto

An explicit directory is also supported and is validated for safe containment. Validation itself enables the cache only when --cache is supplied.

Packaged schemas¶

arch-linter-net schema list
arch-linter-net schema print policy-root

Use these commands for installed/offline schema discovery rather than deriving schema identity from package SemVer.

Architecture Health badge¶

arch-linter-net badge architecture-health \
  --input architecture-health.json \
  --output architecture-health-badge.json

This command reads only the canonical architecture-health/v1 document and its selected architecture-policy-inventory/v1 receipt. It produces one compact Shields payload such as DEBT · 7 ignores · 42 rules: the first term is the canonical non-compensating Health category, ignores is accumulated explicit waiver debt, and rules is the effective policy-control count after policy composition. It does not parse policy YAML, recount findings or waivers, run analysis, or turn the rule count into a quality score.

healthy, debt, degrading, and failing retain the canonical Health category and a deterministic typed color. A missing, malformed, inconsistent, or unassessable Health/inventory input produces UNASSESSABLE · ? ignores · ? rules with a non-green color and exit code 2; unknown is never fabricated as zero. Otherwise the command preserves the Health gate exit category: pass is 0 and fail is 1.

Legacy architecture-policy badge¶

arch-linter-net badge architecture-policy \
  --input architecture-strict.json

This compatibility projection reads an existing strict result into badge endpoint JSON. It does not rerun architecture analysis and remains deliberately narrower than Architecture Health.

Measure-first metrics¶

arch-linter-net measure --policy architecture/dependencies.arch.yml
arch-linter-net measure --format json --metric application-outgoing
arch-linter-net measure --all-contributors

measure is read-only: it evaluates only policy-owned metric definitions and does not create a budget violation, rewrite a policy/baseline, or produce a SARIF report. Human output is the default; JSON uses schema_id: "architecture-metrics-report/v1" and schema_version: 1, and contains the native subject, effective scope, exact value when evaluable, and canonical contributors. By default, each contributor list is bounded to 20; use --max-contributors <n> to set another positive bound or --all-contributors to emit every contributor. JSON retains the full contributor_count and a contributors_truncated marker whenever it bounds a list.

A complete measurement, including a trusted value of zero, exits 0. If a required metric scope is incomplete, the command still reports its typed shared applicability evidence but exits 2. That result is evidence completeness, not an architecture violation or quality score.

Output guidance¶

Use human output for local diagnosis.
Use JSON when downstream tooling needs the complete normalized finding/coverage/build-state model.
Use measure --format json for the separate, versioned read-only metric-report model.
Use SARIF for supported code-scanning projections, noting that not every non-SARIF finding category is representable there.
Use repeatable --report sinks when CI needs multiple formats from one validation run.

When a policy provides applicability evidence, all three formats add the same deterministic completion projection: canonical control identity and provenance, membership/state records, and required/evaluable/unassessable/not_applicable counts. JSON exposes it in assessment_completion and additive applicability_findings; SARIF places the completion data in the run properties and the normalized findings in SARIF results. These counts show evidence completeness—not architecture quality—and do not replace the separately owned effective-rule count.

When Core produces policy-inventory evidence, human and JSON validation output also disclose the canonical effective-control count and explicit waiver debt. The policy_inventory JSON object is the source for downstream architecture Health/report/badge consumers; do not recalculate either number from policy YAML, findings, or exclusion syntax. Its strict/audit/coverage count is repository-level for the selected policy even when validation evaluates only one finding mode. Its waiver records and debt totals use the same selected repository scope; mode-local waiver output still governs only that mode's validation result. Missing inventory evidence is not a zero-debt result.

See Output formats and Timings.