adrs 0.5.1

Command line tool for managing Architecture Decision Records
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

# adrs

[![Crates.io Version](https://img.shields.io/crates/v/adrs)](https://crates.io/crates/adrs)
[![crates.io](https://img.shields.io/crates/d/adrs.svg)](https://crates.io/crates/adrs)
[![CI](https://github.com/joshrotenberg/adrs/workflows/CI/badge.svg)](https://github.com/joshrotenberg/adrs/actions?query=workflow%3ACI)
[![dependency status](https://deps.rs/repo/github/joshrotenberg/adrs/status.svg)](https://deps.rs/repo/github/joshrotenberg/adrs)

A command-line tool for creating and managing [Architecture Decision Records](https://adr.github.io) (ADRs).

## Features

- **adr-tools compatible** - works with existing ADR repositories
- **Multiple formats** - supports Nygard (classic) and [MADR 4.0.0](https://adr.github.io/madr/) 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)

```sh
brew install joshrotenberg/brew/adrs
```

### Cargo

```sh
cargo install adrs
```

### Docker

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

### Binary releases

Download from [GitHub Releases](https://github.com/joshrotenberg/adrs/releases).

## Quick Start

```sh
# 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

```sh
# 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

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

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

### Generate documentation

```sh
# 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:

```toml
[dependencies]
adrs-core = "0.5"
```

```rust
use adrs_core::Repository;

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

See [library documentation](https://docs.rs/adrs-core) for more details.

## Documentation

Full documentation: [joshrotenberg.github.io/adrs-book](https://joshrotenberg.github.io/adrs-book/)

## Contributing

Contributions welcome! See [issues](https://github.com/joshrotenberg/adrs/issues) or open a new one.

## License

MIT or Apache-2.0