adrs

A command-line tool for creating and managing Architecture Decision Records (ADRs).

Features

• adr-tools compatible - works with existing ADR repositories
• Multiple formats - supports Nygard (classic) and MADR 4.0.0 formats
• Template variants - full, minimal, and bare templates
• Repository health checks - doctor command finds issues
• Config discovery - automatically finds ADR directory from subdirectories
• Cross-platform - macOS, Linux, and Windows binaries

Installation

Homebrew (macOS/Linux)

brew install joshrotenberg/brew/adrs

Cargo

cargo install adrs

Docker

docker run --rm -v $(pwd):/work ghcr.io/joshrotenberg/adrs init

Binary releases

Download from GitHub Releases.

Quick Start

# Initialize a new ADR repository
adrs init

# Create your first decision
adrs new "Use PostgreSQL for persistence"

# List all ADRs
adrs list

# Check repository health
adrs doctor

Usage

adrs [OPTIONS] <COMMAND>

Commands:
  init      Initialize a new ADR repository
  new       Create a new ADR
  edit      Edit an existing ADR
  list      List all ADRs
  link      Link two ADRs together
  config    Show configuration
  doctor    Check repository health
  generate  Generate documentation (toc, graph, book)

Options:
      --ng         Enable NextGen mode with YAML frontmatter
  -C, --cwd <DIR>  Run from a different directory
  -h, --help       Print help
  -V, --version    Print version

Examples

Create ADRs with different formats

# Classic Nygard format (default)
adrs new "Use REST API"

# MADR 4.0.0 format
adrs new --format madr "Use GraphQL"

# Minimal template
adrs new --variant minimal "Quick decision"

Supersede and link decisions

# Supersede an existing ADR
adrs new --supersedes 2 "Use MySQL instead"

# Link related ADRs
adrs link 3 "Amends" 1 "Amended by"

Generate documentation

# Table of contents
adrs generate toc > doc/adr/README.md

# Graphviz dependency graph
adrs generate graph | dot -Tsvg > doc/adr/graph.svg

# mdbook
adrs generate book && cd book && mdbook serve

Library

adrs is built on the adrs-core library, which can be used independently:

[dependencies]
adrs-core = "0.5"

use adrs_core::Repository;

let repo = Repository::open(".")?;
for adr in repo.list()? {
    println!("{}: {}", adr.number, adr.title);
}

See library documentation for more details.

Documentation

Full documentation: joshrotenberg.github.io/adrs-book

Contributing

Contributions welcome! See issues or open a new one.

License

MIT or Apache-2.0