A Python CLI for managing Architecture Decision Records.
Compatible with adr-tools workflow. Supports Nygard and MADR templates.
For background on ADRs, see the included paper: Using ADR on GitHub
pip install dark-madrFor development:
uv sync
uv pip install -e .# Initialize ADR directory
adr init
# Create a new ADR
adr new "Use PostgreSQL for primary database"
# List all ADRs
adr list
# Show a specific ADR
adr show 1
# Supersede an existing ADR
adr new "Use PostgreSQL 15" --supersedes 1
# Generate table of contents
adr generate tocConfigure defaults in pyproject.toml:
[tool.adr]
dir = "docs/decisions"
template = "madr"
default_status = "proposed"
default_authors = ["Architecture Team"]Initialize configuration:
adr init-config
adr config # view current settings| Command | Description |
|---|---|
adr init |
Initialize ADR directory with first ADR |
adr new <title> |
Create a new ADR |
adr list |
List all ADRs |
adr show <number> |
Display an ADR |
adr generate toc |
Generate table of contents |
adr templates |
List available templates |
adr config |
Show current configuration |
adr init-config |
Add config section to pyproject.toml |
adr new "Title" --template madr # Use specific template
adr new "Title" --status accepted # Set initial status
adr new "Title" --supersedes 3 # Supersede ADR-0003
adr --adr-dir ./docs list # Override ADR directoryTwo built-in templates:
- nygard (default) - Michael Nygard's original format
- madr - Markdown Any Decision Records format
View template structure:
adr help-template nygard
adr help-template madrCustom templates can be added to a directory specified by template_dir in config.
uv sync --all-extras
uv run pytest
uv run mypy src/
uv run ruff check src/- Documenting Architecture Decisions - Michael Nygard
- Lightweight ADRs - ThoughtWorks Tech Radar (Adopt, Nov 2017)
- adr-tools - Nat Pryce
- MADR - Markdown Any Decision Records
MIT