adrs

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, bare, and bare-minimal templates
• Tags support - categorize ADRs with tags (NextGen mode)
• Full-text search - search ADR titles and content
• Repository health checks - doctor command with configurable rules ([doctor] in adrs.toml) and a pre-commit hook

• Config discovery - automatically finds ADR directory from subdirectories
• Import/Export - JSON-ADR format with federation support
• MCP server - AI agent integration via Model Context Protocol
• Cross-platform - macOS, Linux, and Windows binaries

Installation

Homebrew (macOS/Linux)

brew install adrs

Cargo

cargo install adrs

Docker

docker run --rm -v $(pwd):/workspace -w /workspace 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
  search       Search ADRs for matching content
  link         Link two ADRs together
  status       Change an ADR's status
  config       Show configuration
  doctor       Check repository health