Quickstart

The adr CLI validates a decision corpus, scaffolds new records, explains which decisions govern a file, renders the decision graph, migrates an existing MADR corpus in place, emits the ARB operations queue, and runs the deterministic evaluator.

Published on npm (v0.13.0)

@adrkit/cli is live. Consumers install it with your Node package manager and run the adr binary — no clone required.

Install

Add the CLI to a project, or run it one-off. It exposes the adr binary.

Always name the package: @adrkit/cli

The bare npm package name adr belongs to an unrelated tool. For one-off use, run npx @adrkit/cli … or bunx @adrkit/cli …. After installation, use the adr or adrkit binary.

npm / npx

# one-off, no install — always name the package
npx @adrkit/cli lint
npx @adrkit/cli explain src/payments/api.ts

# or add it to the project and drive it from a script
npm install --save-dev @adrkit/cli
npm pkg set scripts.adr=adr
npm run adr -- lint

# or install globally, for a bare `adr` on your PATH
npm install -g @adrkit/cli
adr lint

Bun

# one-off, no install — always name the package
bunx @adrkit/cli lint
bunx @adrkit/cli explain src/payments/api.ts

# or add it to the project and drive it from a script
bun add --dev @adrkit/cli
bun run adr lint   # with "adr": "adr" in package.json scripts

# or install globally, for a bare `adr` on your PATH
bun add --global @adrkit/cli
adr lint

`adrkit` — the unambiguous installed alias

Every install above also provides a second binary, adrkit, identical to adr. Prefer adrkit in shared scripts and agent instructions. For one-off use, continue to name the package: npx @adrkit/cli lint.

The examples below are written as bare adr … for readability. A local install does not put adr on your shell PATH; run it through your package script, such as npm run adr -- lint.

Create your first record — adr new

If you have no docs/adr/ yet, start here: adr new creates the directory and writes the first record, so it is the bootstrap step as well as the everyday one. Running adr lint first on a repository with no corpus exits 2 with Corpus directory not found: 'docs/adr'.

Already have MADR records?

Go to Adopt an existing MADR corpus first. What adr lint reports depends on your filenames. Records already named NNNN-slug.md are read and fail on the required fields (id, title, status, date) and on unknown keys. Descriptively named files are not discovered at all — they are reported as skipped warnings, so lint checks 0 records and exits 0, which is not the same as passing. adr migrate adds the fields in place, and --rename fixes the filenames.

Scaffold a record with the next sequential id and valid frontmatter.

adr new "Use server-side rendering for authenticated routes"
# choose a starting status (accepted/superseded need extra fields and are refused)
adr new "Adopt OpenTelemetry" --status proposed

That writes docs/adr/0001-use-server-side-rendering-for-authenticated-routes.md with affects: []. Filling affects in is what makes the decision locatable by CI and agents — a record with no affects is advisory only. Each entry is a type plus a pattern:

affects:
  - type: path
    pattern: "apps/web/app/**"
  - type: package
    pattern: "next@>=16"

type is one of path, package, api, resource, entity, or data. See the JSON Schema reference for the full field list.

Path patterns are globs, so escape literal brackets

(, ), [, ], {, }, !, and * are glob syntax. A Next.js route group written as apps/web/app/(authed)/** compiles to a group matching the text authed, so it matches apps/web/app/authed/** and never the directory literally named (authed) — and it fails silently, because a pattern that matches nothing is not an error. Escape them: apps/web/app/\(authed\)/**.

When each matcher resolves

path matchers resolve everywhere — adr explain, adr check, CI, and the MCP server. A package matcher needs a changed-dependency snapshot, which today only the CI Action supplies, and only from a changed bun.lock. Everywhere else it is reported as inert rather than matched, so a record whose only matcher is package will not surface locally.

Validate a corpus — adr lint

Validate every record under docs/adr/ against the schema, enforce unique ids, flag dangling references between records (supersedes / supersededBy / relatesTo / conflictsWith), and warn when an accepted record declares a conflict via conflictsWith.

adr lint
# lint a specific directory or files
adr lint --dir docs/adr
adr lint docs/adr/0001-record-architecture-decisions-in-git.md
# machine-readable output for CI
adr lint --json

adr lint exits non-zero when it finds errors, so it drops straight into a CI gate.

Explain what governs a file — adr explain

Print every decision that matches a path, and the matcher that fired. Only accepted records are reported as governing; matched proposals and superseded, rejected, or deprecated records are listed under their own headings so a rejected decision is never presented as binding.

adr explain packages/core/src/schema/adr.schema.ts
adr explain package.json --json

Render the decision graph — adr graph

Inspect the decision graph interactively, or emit deterministic DOT, Mermaid, or JSON for another tool. Bare adr graph shows a compact terminal instrument when stdout is a TTY and preserves DOT when piped or redirected.

# interactive overview, then one readable neighborhood
adr graph
adr graph --focus 0014
# GitHub-compatible Mermaid source
adr graph --format mermaid > decisions.mmd
# styled Graphviz DOT rendered to SVG
adr graph --format dot | dot -Tsvg > decisions.svg
# structured JSON
adr graph --format json

Adopt an existing MADR corpus — adr migrate

Migrate a MADR corpus in place, additively and non-destructively. The migration is one-way; round-trip sync is deliberately unsupported (ADR-0008).

Status, date, and deciders are read from MADR 3.x YAML frontmatter, MADR 2.x * Status: header bullets, and Nygard ## Status sections, so an already-accepted corpus does not import as a backlog of proposals attributed to nobody.

# preview without writing
adr migrate --from madr --dry-run
# apply
adr migrate --from madr --dir docs/adr

Corpus discovery requires <id>-<slug>.md filenames. If your MADR files use descriptive names, migration warns that the records will not be discoverable — pass --rename to move each file to a discoverable name as part of the run:

adr migrate --from madr --dir docs/adr --rename

Next steps

• Enforce decisions on every PR — see Use in CI.
• Evaluate the proposed generated-wiki boundary — see Use with generated knowledge systems (provisional, pending ratification).
• Give agents the decision graveyard — see MCP setup.
• Discover commands, enable shell completion, configure color, and check every exit code — see the Command reference.
• Reference the schema from your editor and CI — see the JSON Schema.
• Read how adrkit governs itself in the decision records.