Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

adrs is a command line tool for creating and managing Architecture Decision Records (ADRs).

What are ADRs?

Architecture Decision Records are short documents that capture important architectural decisions made during a project. Each ADR describes a single decision, including the context, the decision itself, and its consequences.

Features

  • adr-tools compatible: Works with existing ADR repositories created by adr-tools
  • Multiple formats: Supports both Nygard (classic) and MADR 4.0.0 formats
  • Template variants: Full, minimal, and bare templates for each format
  • Cross-platform: Binaries available for Linux, macOS, and Windows
  • Library support: Use adrs-core as a Rust library in your own tools

Quick Start

Installation

Using the shell installer (Linux/macOS):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/joshrotenberg/adrs/releases/latest/download/adrs-installer.sh | sh

Using PowerShell (Windows):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/joshrotenberg/adrs/releases/latest/download/adrs-installer.ps1 | iex"

Using Homebrew:

brew install joshrotenberg/brew/adrs

Using Cargo:

cargo install adrs

Initialize a Repository

adrs init

This creates:

  • A .adr-dir file pointing to doc/adr
  • The doc/adr directory
  • An initial ADR: 0001-record-architecture-decisions.md

Create a New ADR

adrs new "Use PostgreSQL for persistence"

This opens your editor with a new ADR from the default template. Save and close to create the record.

List ADRs

adrs list

adrs link 2 "Amends" 1 "Amended by"

Migration from adr-tools

adrs is designed to be a drop-in replacement for adr-tools. Your existing ADR repository will work without changes:

  1. Install adrs
  2. Run commands as usual - adrs reads the existing .adr-dir file and ADR documents

For new features like MADR format or YAML frontmatter, see the Configuration chapter.

Next Steps