Address (ad)

A CLI for managing Architecture Decision Records (ADRs) in your repository.

ad helps teams capture architectural decisions in a lightweight, git-friendly format so context does not get lost over time.

Why Address?

• Simple CLI workflow for creating and evolving ADRs
• Git-friendly storage using JSONL in a local .adr/ directory
• Search + filtering for quickly finding decisions
• Versioned ADR updates so decision history remains visible
• Agent onboarding command to append ADR guidance to AGENTS.md and CLAUDE.md

Install

bun add @matthamlin/address

You can run the CLI as:

• ad <command> (if your shell resolves local bins)
• bunx ad <command> (recommended, explicit)

Quick Start

# 1) Initialize ADR storage in the current repo
bunx ad init

# 2) Create your first ADR (interactive)
bunx ad new

# 3) List ADRs
bunx ad list

# 4) View one ADR
bunx ad show adr-1234abcd

Command Reference

ad init

Initialize an ADR repository in the current directory.

Creates .adr/ with default files.

ad new / ad create

Create an ADR.

• Interactive mode when running in a TTY
• Non-interactive mode (CI/scripts) via flags:

bunx ad new \
  --title="Use Bun for tooling" \
  --context="Need fast installs and script execution" \
  --decision="Standardize on Bun for package management and scripts" \
  --consequences="Faster CI and local workflows; requires Bun familiarity" \
  --status=accepted \
  --tags=tooling,build \
  --author="Platform Team"

Required in non-interactive mode:

• --title
• --context
• --decision
• --consequences

Optional:

• --status (proposed|accepted|rejected|deprecated|superseded)
• --tags (comma-separated)
• --author

ad list

List ADRs, newest first.

Optional filters:

• --status=<status>
• --tag=<tag>

Examples:

bunx ad list --status=accepted
bunx ad list --tag=security

ad show <id>

Display full ADR details including context, decision, consequences, version, timestamps, tags, and relationship fields.

ad update <id>

Interactively update an ADR.

Behavior notes:

• Content/status/relationship changes increment version
• Tag-only updates do not increment version
• Some status-based update restrictions are enforced (for example, superseded ADRs are immutable)

ad delete <id>

Delete an ADR after explicit confirmation.

ad search <query>

Full-text search over ADR content (title, context, decision, consequences).

ad backup

Create a snapshot backup of .adr/adrs.jsonl.

Backups are stored in .adr/backups/ and rotated (up to 10 by default).

ad onboard

Append ADR usage instructions to AGENTS.md and CLAUDE.md in the current directory (if present and not already documented).

Useful for making ADR workflows discoverable to AI coding agents.

ad help

Show CLI help and usage summary.

Global Options

• --help, -h — show help
• --version — show version

ADR Status Values

• proposed
• accepted
• rejected
• deprecated
• superseded

ADR Data Model

Each ADR includes:

• id (e.g. adr-a1b2c3d4)
• title
• status
• context
• decision
• consequences
• version
• createdAt
• updatedAt

Optional fields:

• decidedAt
• tags
• author
• supersedes
• supersededBy
• relatedTo
• stakeholders
• metadata

Storage Layout

After ad init, the default structure is:

.adr/
  adrs.jsonl
  index.json
  config.json
  backups/

• adrs.jsonl: one JSON object per line (all ADRs)
• index.json: lookup/index metadata
• config.json: initialized storage config snapshot
• backups/: rotated backup files created by ad backup

Best Practices

• Keep ADR titles short and specific
• Record trade-offs in Consequences, not just benefits
• Use tags for filtering (security, data, api, etc.)
• Prefer creating a new ADR + supersession when a decision fundamentally changes
• Commit .adr/ to git so ADR history evolves with code history