# Install adr-tools with Homebrew, apt, Nix CLI tool for working with Architecture Decision Records. Version 3.0.0 via Homebrew; verified 2026-05-26. ## Install ```sh sudo av install brew:adr-tools ``` Additional install commands: ### macOS - Homebrew (100%): ```sh brew install adr-tools ``` Evidence: local Homebrew formula metadata ### Linux - Debian apt (92%): ```sh sudo apt install adr-tools ``` Evidence: Debian stable package indexes: adr-tools from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz - Nix (92%): ```sh nix profile install nixpkgs#adr-tools ``` Evidence: nixpkgs package indexes: pkgs/by-name/ad/adr-tools/package.nix from https://api.github.com/repos/NixOS/nixpkgs/git/trees/master?recursive=1 ## Package facts - **Package key:** brew:adr-tools - **Package manager:** Homebrew - **Package manager page:** - **Version:** 3.0.0 - **Source summary:** CLI tool for working with Architecture Decision Records - **Homepage:** - **Repository:** - **Upstream docs:** - **License:** CC-BY-4.0 - **Source archive:** - **Last updated:** 2026-05-26T23:37:49-04:00 - **Generated:** 2026-07-08T07:18:31+00:00 ## Executables - _adr_add_link (cli) - _adr_autocomplete (cli) - _adr_commands (cli) - _adr_dir (cli) - _adr_file (cli) - _adr_generate_graph (cli) - _adr_generate_toc (cli) - _adr_help (cli) - _adr_help_new (cli) - _adr_links (cli) - _adr_remove_status (cli) - _adr_status (cli) - _adr_title (cli) - adr (cli) - adr-config (cli) - adr-generate (cli) - adr-help (cli) - adr-init (cli) - adr-link (cli) - adr-list (cli) - adr-new (cli) - adr-upgrade-repository (cli) - _adr_add_link (alias) - _adr_autocomplete (alias) - _adr_commands (alias) - _adr_dir (alias) - _adr_file (alias) - _adr_generate_graph (alias) - _adr_generate_toc (alias) - _adr_help (alias) - _adr_help_new (alias) - _adr_links (alias) - _adr_remove_status (alias) - _adr_status (alias) - _adr_title (alias) - adr (alias) - adr-config (alias) - adr-generate (alias) - adr-help (alias) - adr-init (alias) - adr-link (alias) - adr-list (alias) - adr-new (alias) - adr-upgrade-repository (alias) ## Install behavior - Post-install hook: not defined - Bottle: available on all ## Freshness - Page generated: 2026-07-08 - Package-manager version: 3.0.0 - Package-manager updated: 2026-05-26 - Local data: ok - Upstream repository: https://github.com/npryce/adr-tools - Upstream latest detected: 3.0.0 (current) ## Project history and usage ADR Tools is Nat Pryce's shell-based command-line toolkit for creating and maintaining Architecture Decision Records in a source tree. It became one of the reference implementations for teams that wanted ADRs as simple numbered Markdown files rather than a hosted documentation system. ### Project history The project records its own first ADR on 2016-02-12, deciding to use Architecture Decision Records for its architecture decisions. Its README positions the tool around a log of ADRs, with Markdown records stored under a project subdirectory, defaulting to `doc/adr`. ADR Tools deliberately uses Unix shell scripts. The project ADR directory includes decisions such as implementing the tool as shell scripts, using a single command with subcommands, storing records in Markdown, invoking `adr-config` for installation-specific configuration, and using ISO-8601 dates. The 2018 release series added repository upgrades, ISO-8601 date format support, arbitrary links between ADRs, graph visualisation output, generated tables of contents, bash completion, better help text, Git Bash support on Windows, and parent-directory search for ADR directories. ### Adoption history ADR Tools adopted the same source-control-native posture as ADRs themselves: its install documentation recommends Homebrew on macOS, release archives or Git on Linux/macOS, Git Bash or WSL on Windows, and shell autocomplete installation where supported. The provided package metadata shows distribution through Homebrew, Debian, Ubuntu, and Nix. The GitHub repository's large star and fork counts also reflect broad recognition among architecture-documentation users, but its day-to-day adoption is usually invisible because the generated ADR files live inside other projects' repositories. ### How it is used The common workflow is `adr init` to create an ADR directory, `adr new` to create a numbered Markdown record, and `adr help` for subcommands. The README says new records are opened in the user's editor through `VISUAL` or `EDITOR`. Teams use it to keep architectural decisions close to code, review them like any other text change, and link or supersede older decisions as architecture changes. Generated graphs and tables of contents make it useful beyond the first few records. ### Why package nerds care ADR Tools is package-nerd significant because it is a tiny shell distribution that turns an architectural practice into a Unix command. Its behavior is easy to audit, easy to vendor, and easy for package managers to ship without a runtime stack beyond POSIX-ish shell tooling. It also shaped conventions that other tools follow, especially the default `doc/adr` directory and numbered Markdown filenames. That convention is visible in adr-viewer, which defaults to the same path because ADR Tools generates it. ### Timeline - 2016: Project ADR 1 recorded the use of Architecture Decision Records. - 2016: Early ADRs chose shell scripts, a single command with subcommands, and Markdown format. - 2018: Version 2.0.0 added ISO-8601 dates and repository upgrade support. - 2018: Version 2.1.0 added arbitrary links and Graphviz history/relationship output. - 2018: Version 2.2.0 added better help, bash autocomplete, and Git Bash support. - 2018: Version 3.0.0 added parent-directory ADR discovery and graph layout improvements. ### Related projects - adr-viewer consumes ADR directories and defaults to ADR Tools' `doc/adr` path. - Michael Nygard's ADR article is linked from the README as the conceptual source for the record format and practice. ### Sources - - - - - - source_facts.package-manager ## Security Notes broad file, network, media, or database tool signal. - **Geiger risk:** blue / medium - broad file, network, media, or database tool signal ## Source Database Details - **Source Database:** Homebrew formula API - **Tap:** homebrew/core - **Full Name:** adr-tools - **Version Scheme:** 0 - **Revision:** 0 - **Bottle Stable Root URL:** - **Deprecated:** no - **Disabled:** no - **Keg Only:** no - **URL Keys:** stable ## Other Package-Manager Records - Debian apt - adr-tools - 3.0.0-2: normalized package name match | Debian stable package indexes: adr-tools from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz | tools for working with a log of Architecture Decision Records | https://github.com/npryce/adr-tools - Nix - adr-tools: normalized package name match | nixpkgs package indexes: pkgs/by-name/ad/adr-tools/package.nix from https://api.github.com/repos/NixOS/nixpkgs/git/trees/master?recursive=1 - Ubuntu apt - adr-tools - 3.0.0-2: normalized package name match | Ubuntu 24.04 LTS package indexes: adr-tools from https://archive.ubuntu.com/ubuntu/dists/noble/universe/binary-amd64/Packages.gz | tools for working with a log of Architecture Decision Records | https://github.com/npryce/adr-tools ## Related links - [Source-control packages](https://www.automicvault.com/pkg/source-control-tools/) - Belongs to a source-control command family. - [Secret-risk packages](https://www.automicvault.com/pkg/secret-risk-packages/) - Has protected-tool coverage, approval-gate, or non-low Geiger security signals. - [Terminal utility packages](https://www.automicvault.com/pkg/terminal-utilities/) - Matched terminal and command-line workflow metadata. - [Text processing packages](https://www.automicvault.com/pkg/text-processing-tools/) - Matched text, document, or structured-data processing metadata. - [adr-viewer](https://www.automicvault.com/pkg/brew/adr-viewer/) - Shares av.db curated category or tags: adr, cli, developer-tools, documentation. - [action-docs](https://www.automicvault.com/pkg/brew/action-docs/) - Shares av.db curated category or tags: cli, developer-tools, documentation. - [cargo-docset](https://www.automicvault.com/pkg/brew/cargo-docset/) - Shares av.db curated category or tags: cli, developer-tools, documentation. - [cheat](https://www.automicvault.com/pkg/brew/cheat/) - Shares av.db curated category or tags: cli, developer-tools, documentation. - [context7-mcp](https://www.automicvault.com/pkg/brew/context7-mcp/) - Shares av.db curated category or tags: cli, developer-tools, documentation. - [cppman](https://www.automicvault.com/pkg/brew/cppman/) - Shares av.db curated category or tags: cli, developer-tools, documentation. - [dita-ot](https://www.automicvault.com/pkg/brew/dita-ot/) - Shares av.db curated category or tags: cli, developer-tools, documentation. - [doc8](https://www.automicvault.com/pkg/brew/doc8/) - Shares av.db curated category or tags: cli, developer-tools, documentation. - [adr-tools](https://www.automicvault.com/pkg/npm/adr-tools/) - Same normalized package name appears in another local ecosystem. Shared terms: adr, adr-tools, architecture, decision, records. - [adr-tools](https://www.automicvault.com/pkg/npm/adr-tools/) - Same normalized package name in another local ecosystem. ## Combined YAML source View the package source record on GitHub. [combined/adr-tools.yml](https://github.com/automic-vault/db/blob/main/combined/adr-tools.yml) ## Sources - Nucleus package database - Geiger risk classifier - package-page enrichment - curated package history - package version freshness - av.db category and tag curation - package relationship graph - external package-manager database matches - cross-ecosystem install command graph