The CLI
The architecture CLI checks the same manifest as the oxlint plugin, without a linter. Run it in
CI next to oxlint: it also evaluates graph rules
and writes baselines, which the plugin can’t.
| Command | What it does |
|---|---|
check |
Evaluate the policy. The default when no command is given. |
conformance |
Measure how far the tree is from the policy. |
baseline |
Record the violations the repository has today. |
coverage |
Show how much of the tree each rule family reaches. |
explain |
Show every rule that governs a file. |
facts |
Show what the parser read out of a file. |
init |
Write a starter architecture.yaml. |
infer |
Write a manifest describing the tree as it is. |
migrate |
Convert a JavaScript manifest to architecture.yaml. |
campaigns, objectives |
Campaign commands; see Campaigns → Commands. |
Roots. Commands that take [roots…] walk those directories, defaulting to packages. For
TypeScript the walk reads .ts, .tsx, .mts and .cts (not .d.ts) and skips node_modules,
build, dist, .next and coverage.
Manifest. Found in the working directory as architecture.yaml, .yml, .json or
architecture.config.mjs (exactly one may exist), or named by the ARCHITECTURE_CONFIG environment
variable.
Exit codes. 0 on success, 1 on failure, with the reason on stderr. Unknown commands and a
manifest that fails to load exit 1.
Graph rules
Section titled “Graph rules”Only check (and conformance) evaluate graph rules: the plugin sees one file at a time. Both the
plugin and the CLI still probe graph rules at load, so a rule that can’t fire fails either one.
architecture check [--json] [roots…]| Flag | Meaning |
|---|---|
--json |
Print one JSON object on stdout. The failure reason still goes to stderr. |
Exits 1 on any unbaselined violation, unresolved import, stale baseline entry, coverage below a
floor, conformance measure above a ceiling, or failing campaign. Each finding names its rule by its
node path in the manifest.
packages/server/src/modules/user/domain/user/user.root.ts [modules-module/domain/{subdomain}/imports] domain/ holds the model — no framework, no persistence, no bus.
1284 files, 1 violations, 37 carried by the baselineIn scripts, assert on --json output, not the text:
{ "version": 1, "files": 90, "roots": ["packages"], "ok": false, "manifest": { "path": "architecture.yaml", "sha256": "…" }, "violations": [ { "fingerprint": "import|cli/imports|packages/cli/src/x.ts|packages/oxlint/src/y.ts", "kind": "import", "ruleName": "cli/imports", "file": "packages/cli/src/x.ts", "subject": "packages/oxlint/src/y.ts", "message": "…", "baselined": false } ], "unresolved": [{ "file": "…", "specifier": "…", "detail": "…" }], "stale": ["<fingerprint>"], "coverage": { "imports": { "covered": 90, "total": 90, "floor": 1 } }, "conformance": { "slack": { "count": 4, "ceiling": 5 } }, "adoption": { "unrestricted": [], "partial": [] }}| Field | Meaning |
|---|---|
ok |
true only when nothing would fail the run. |
manifest |
The manifest path and a hash of it (the root file only, when split with include). |
violations |
Every finding, baselined included. fingerprint is the baseline key. |
stale |
Baseline entries the code no longer produces. |
coverage |
Per family, as coverage prints, with floor when one is set. |
conformance |
Per measure, with ceiling when limits.conformance sets one. |
version |
The shape’s version. |
conformance
Section titled “conformance”architecture conformance [--json] [--against <manifest>] [roots…]| Flag | Meaning |
|---|---|
--json |
Print the snapshot document. |
--against <manifest> |
Measure against another manifest. Only conformance takes it. |
Always exits 0 once the policy loads. See Conformance.
baseline
Section titled “baseline”architecture baseline [roots…]Rewrites the file named by the manifest’s baseline key from every current violation. Exits 1 if
the manifest declares no baseline. See Adoption.
coverage
Section titled “coverage”architecture coverage [roots…]Prints each family’s reach, plus the unrestricted and partial tiers. Doesn’t fail on floors;
check does. See Adoption.
explain
Section titled “explain”architecture explain <file> [roots…]Shows the rules that govern one file: the import allowlist in force after inheritance, every
prohibition that reaches it, the folder rule that admits it, the siblings it owes, and any
exports, members, surface, graph and campaign rules that select it. Run it first when a rule
fires too much or not at all.
$ architecture explain packages/server/src/modules/todos/commands/create-todo.handler.ts
may import: — modules-module/commands/imports ^node:.* ^packages/server/src/modules/$1/domain(/.*)? /node_modules/effect/
may not import: modules-module/deny-1 — A module may only import another module through its index.ts barrel.
lives in: modules-module/commands/layout owes: packages/server/src/modules/todos/commands/create-todo.handler.test.tsThe allowlist shows compiled regular expressions. $1 is a
capture filled from this file’s path.
For a campaign, it prints the file’s sector and phase, the objectives in window (✗ marks one firing here), the nearest holdouts, and a truth table: every leaf term of each detector and what it answered for this file.
architecture facts <file> [--json]| Flag | Meaning |
|---|---|
--json |
Print the facts as one JSON object. |
Shows what rules are evaluated against: import edges and bindings, members, calls, and exports.
$ architecture facts packages/server/src/modules/todos/commands/create-todo.handler.ts
edges: effect namespace * ../domain/todo/todo.root.ts named Todo server-only (no bindings) members: CreateTodoDeps.todos (type) calls: makeCommandHandler exports: named createTodo (variable)If a rule should fire and doesn’t: when the site is listed here, the rule’s pattern doesn’t select
it (check explain); when it isn’t, the parser doesn’t read that syntax.
What counts as an import edge:
import "m"; // side-effect: no bindingsimport x, { a, b as c } from "m"; // default, namedimport * as ns from "m"; // namespaceimport type { T } from "m"; // type-only is still an edgeexport { a, b as c } from "m";export * from "m";export * as ns from "m";import x = require("m");await import("m"); // string literal argument onlyrequire("m"); // string literal argument onlyA computed specifier is not an edge. Forms that take the whole module (import * as, export *,
export * as, import =, import(), require()) carry one namespace binding named *.
Calls are named by identifier or property: f() and x.f() are both f. Computed
(x[f]()) and private (x.#f()) calls are not reported.
architecture initWrites a starter architecture.yaml: one open root, both adoption ceilings at zero, and comments
linking to the docs. Exits 1 if any manifest file already exists.
architecture infer [--depth N] [--root DIR]... [--tsconfig PATH] [--write] [--yes | --exhaustive] [--collapse]Prints a manifest that describes the tree as it is: check passes on it with zero violations. See
Starting from the tree.
| Flag | Meaning |
|---|---|
--depth N |
Folder levels below each package’s src/ that become nodes. Default 2. Deeper folders fall under a **/ catch-all. |
--root DIR |
A folder to walk and a top-level key. Repeatable. Default: the manifest’s top-level keys, else src/, else every top-level folder with source. |
--tsconfig PATH |
Tsconfig to resolve through when there’s no manifest. Default tsconfig.json. With a manifest, its resolve and aliases are reused. |
--write |
Save as architecture.yaml instead of printing. Refuses to overwrite a manifest. |
--yes |
Answer every question yes. |
--exhaustive |
Ask nothing; describe every folder on its own. The default off a terminal. |
--collapse |
Fold a node’s children into it when every child reaches the same things. |
Sibling folders with the same shape are offered as one wildcarded node (modules/{module}/), one question each. The output sets limits.unrestricted and limits.coverage to today’s numbers. Unresolved imports are listed on stderr. An unknown flag exits 1.
migrate
Section titled “migrate”architecture migrateRewrites the JavaScript manifest (found by name or via ARCHITECTURE_CONFIG) as
architecture.yaml. Comments are lost. Exits 1 if the module fails to decode, if the manifest is
already a data file, or if architecture.yaml exists. Delete the module afterwards: two manifests
are refused. See Organizing a manifest.