decree

Python 3.11+ reimplementation of adr-tools with a typed API and a Typer CLI.

install

Decree is published on PyPI and can be installed on Linux, macOS, or Windows. We recommend using either pipx or uv for a clean, isolated installation.

Install with pipx

pipx installs Python CLI tools in their own virtual environments so they do not interfere with system packages.

pipx ensurepath
pipx install decree
decree --help

Upgrade:

pipx upgrade decree

Uninstall:

pipx uninstall decree

Works on Ubuntu, Debian, macOS, and Windows. Uses your system Python (3.11 or newer). No sudo is required for the app itself.

Install with uv

uv is a Rust-based Python toolchain designed for speed and reproducibility.

Install uv: guide

Install decree:

uv tool install decree
decree --help

Upgrade:

uv tool upgrade decree

Uninstall:

uv tool uninstall decree

uv does not require system Python once installed.

quickstart

decree init
decree new Use beartype on public API
decree list
decree generate toc > doc/adr/README.md
decree generate graph  # exits non-zero, not implemented

cli

• decree init [DIR]
• decree new [--status STATUS] [--template PATH] [--dir DIR] [--date YYYY-MM-DD] TITLE...
• decree link SRC REL TGT [--reverse / --no-reverse]
• decree list
• decree generate toc
• decree generate graph (not implemented)
• decree upgrade-repository

exit codes

Decree follows sysexits where available and falls back to portable numbers on platforms such as Windows. The fallback values are listed below; on POSIX you will see the native os.EX_* numbers (for example, usage errors exit with 64).

Examples:

decree new "Valid ADR"              # -> 0
decree new --template missing.md foo # -> 66 (missing template)
ADR_DATE=bad-date decree new Foo     # -> 78 (invalid config)

Contributors should raise click.UsageError for argument problems and click.ClickException with ExitCode for domain failures. See the Click exception guide for details.

configuration

• ADR_DATE: if set, used verbatim as the ADR date after validation
• ADR_TEMPLATE: path to a custom template file

Template precedence is explicit CLI flag first, then the environment variable, then the built-in default:

ADR_TEMPLATE=/path/to/template.md decree new "Use beartype"
decree new --template /other/path.md "Use beartype"  # CLI overrides env var

dependabot

Dependabot checks uv dependencies and GitHub Actions every Monday at 09:00 America/Los_Angeles. Edit .github/dependabot.yml to change the schedule window, and adjust the groups block if you want different buckets for runtime versus dev tooling updates.

Date handling and reproducibility

New ADRs always render Date: YYYY-MM-DD in their front matter. By default, the current local date is used. Supply --date YYYY-MM-DD or set the ADR_DATE environment variable to override the value (the CLI flag takes precedence). Any override must already be in ISO format; otherwise, the command exits with an error.