Skip to content
adrkit

Quickstart

The adr CLI validates a decision corpus, scaffolds new records, explains which decisions govern a file, renders the decision graph, and migrates an existing MADR corpus in place.

Install

Section titled “Install”

adrkit is built with Bun (ADR-0010). Install Bun, then clone the repository and install dependencies.

  1. Install Bun:

    Terminal window
    curl -fsSL https://bun.sh/install | bash

  2. Clone and install:

    Terminal window
    git clone https://github.com/mbeacom/adrkit.git
    cd adrkit
    bun install

  3. Validate the bundled corpus to confirm the CLI works:

    Terminal window
    bun run adr lint

The examples below use bun run adr <command>. Once a published binary lands, the same commands run as adr <command> (or npx adr <command>).

Validate a corpus — adr lint

Section titled “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.

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

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

Create a record — adr new

Section titled “Create a record — adr new”

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

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

Fill in affects — it is what makes a decision locatable by CI and agents. A record with no affects is advisory only. See the JSON Schema reference for every field.

Explain what governs a file — adr explain

Section titled “Explain what governs a file — adr explain”

Print every decision governing a path, and the matcher that fired.

Terminal window
bun run adr explain packages/core/src/schema/adr.schema.ts
bun run adr explain package.json --json

Render the decision graph — adr graph

Section titled “Render the decision graph — adr graph”

Emit the decision graph — supersession and relationships — as Graphviz DOT or JSON.

Terminal window
# Graphviz DOT (pipe into `dot -Tsvg`)
bun run adr graph --format dot
# structured JSON
bun run adr graph --format json

Adopt an existing MADR corpus — adr migrate

Section titled “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).

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

Next steps

Section titled “Next steps”