Skip to content

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.

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.

Terminal window
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 baseline

In 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.
Terminal window
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.

Terminal window
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.

Terminal window
architecture coverage [roots…]

Prints each family’s reach, plus the unrestricted and partial tiers. Doesn’t fail on floors; check does. See Adoption.

Terminal window
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.ts

The 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.

Terminal window
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 bindings
import x, { a, b as c } from "m"; // default, named
import * as ns from "m"; // namespace
import type { T } from "m"; // type-only is still an edge
export { a, b as c } from "m";
export * from "m";
export * as ns from "m";
import x = require("m");
await import("m"); // string literal argument only
require("m"); // string literal argument only

A 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.

Terminal window
architecture init

Writes 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.

Terminal window
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.

Terminal window
architecture migrate

Rewrites 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.