ADR is a command-line tool that is used to create and maintain Architecture Decision Records as described by Michael Nygård in The following blog article.

The tool is built and packaged as a DotNet Tool. If you just want to install it, then type the following into your console of choice:

> dotnet tool install -g ADR-Cli --version 2.0.0

Or to update:

> dotnet tool update -g ADR-Cli --version 2.0.0

Which should hook you up with the latest version.

ADR is slightly opinionated in that:

• It requires that you have VS Code installed on your system
• It requires that you are using Git as your version control system
• It assumes that you want your ADRs saved to your repository root folder /doc/adr
• It requires that the index file is named 0000-index.md (it will create this file when required)

If you can live with these requirements and assumptions, then you're set.

To invoke the command, just type adr, or if you want to manage ADRs in a different folder than your current directory, just provide an absolute or relative path to a folder where ADRs exist.

> adr ./code/myProject

NOTE
ADR will provide an error message if you run it "outside" a git repository folder. However, it does not matter how deep into a repository folder structure you are, it will figure out where to find the doc/adr once started.

If this is the first time you're using ADR, and you run the tool, you will be asked whether you would like adr to create the doc/adr folder for you. Once you confirm, adr will create the folder, and also an index file and your first ADR entry (pointing to the decision of using ADRs, to begin with).

Once you have your initial folder and files in place, adr, when invoked, will show you a table over all your ADRs so far in that repository, and provides you with a menu to perform some simple operations:

• Arrow up/down to highlight an ADR. [ENTER] opens it in VS Code.
• Pressing A creates a new ADR, prompting you for a title first, then it opens up a template in VS Code
• Pressing R renames the currently highlighted ADR
• Pressing S will create a new ADR that supersedes (overrules) the currently selected one in the table)
• Pressing O opens the entire ADR folder in VS Code. Handy if you need to multi-edit
• Pressing I will recreate the 0000-index.md file based on the adr folder contents

After every "command", the adr tool exits. It does not return to the menu.

NOTE
It is not possible to delete an ADR using the tool. This is because ADRs are supposed to be a forward-only record of important decisions. However, nothing prevents you from fiddling with the files in this folder. This is not rocket science :)

ADR has very few parameters:

> adr
# with no parameters, assumes the current directory as the operating directory

> adr .
> adr ./code/someRepo/src/
# Accepts relative paths

> adr C:\dev\work\AdrTool\Adr
# Also accepts complete paths

> adr --help
# Should display version and a very rudimentary instruction

Once you're comfortable with adr you may want to speed things up. Version 1.0.2 introduces the concept of quickmode commands. Currently, these are:

Creates a new ADR document without a confirmation prompt.

# title: Required. The title of the new ADR to add
# path: Optional. Absolute or relative path to your project folder
> adr new "Prefer Azure ServiceBus for cross-service messaging"

Open up your ADR folder in VS Code

# path: Optional. Absolute or relative path to your project folder
# Example:
> adr open
> adr open .
> adr open /mnt/e/dev/work/myproject