The CLI

arch-check checks one repository against its pinned slice of the architecture model. Its inputs are files, so it runs the same way on a laptop and in any CI.

Installing it

How customers get arch-check: to be confirmed. It needs Python 3.11 or later.

The repository you check doesn’t need to be installed: the check reads the import graph from the files (grimp) and imports nothing.

`arch-check check`

arch-check check --repo . --slice architecture/index.json --json-out architecture-check.json

Argument	Default	What
`--repo`	`.`	the checkout to check
`--slice`	`<repo>/architecture/index.json`	the pinned slice of the model
`--json-out`	none	where to write the result as JSON (optional)

What it checks

Four checks, in this order:

Check	What it reports	Fails the run
contracts	the Import Linter contracts in `pyproject.toml` differ from the ones the model generates	yes
drift	a component in the code but not in the model, or an import the model doesn’t declare (violations); a component in the model but not in the code, or a declared import the code no longer uses (drift)	violations only
interfaces	a component declares an interface file, such as `openapi.json`, that is missing or isn’t an OpenAPI 3 document with paths	yes
adrs	a file cites an ADR that the pinned slice doesn’t hold	yes

Rules and findings lists the rule ID each message becomes.

Output

Each violation and drift line goes to stderr, followed by one summary line on stdout, such as check_architecture: 2 violation(s), 1 drift; ….
With --json-out, the result is written as JSON:

{
  "project": "shop",
  "slice_version": "…",
  "index_version": "…",
  "components": { "shop.api": "verified", "shop.storage": "drift" },
  "violations": ["drift: shop.api imports shop.billing, which the model doesn't declare"],
  "drift": ["drift: shop.legacy is in the model but not in the code"]
}

The result has no timestamp: the same commit always gives the same file.

Exit codes

Code	Meaning
`0`	no violations (drift alone doesn’t fail the run)
`1`	at least one violation
`2`	bad arguments

Files it reads

Inside a Git checkout, the ADR check reads the files Git tracks, plus untracked files Git doesn’t ignore. Outside one, it reads every file.

`arch-check report`

A report of what a pull request changes compared with its base branch: the components it touches, dependency and contract changes, and the ADRs it cites.

arch-check report --base REF [--repo DIR] [--slice FILE]

--base is required: the branch or commit to compare with, such as origin/main. The checkout needs that history (in GitHub Actions, fetch-depth: 0).
It prints Markdown, ready for a job summary.
Exit codes: 0 when the report is written, 2 when --base is missing, 1 when Git can’t read the base.

Languages

Language	Status
Python	supported: the import graph from grimp, boundaries as Import Linter contracts
JavaScript and TypeScript	coming soon (dependency-cruiser)
Go	coming soon

Other CI systems

Because the inputs are files, the same command runs in GitLab CI, Jenkins, Buildkite or any other CI. The dashboard reads results from GitHub Actions today; reading them from other CI systems, starting with GitLab, is coming soon.