decree 0.1.0

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

decree

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

install

pipx install decree
# or after release: brew install steven-cutting/decree/decree

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).

Fallback	ExitCode member	Meaning
0	ExitCode.SUCCESS	Successful run.
1	ExitCode.GENERAL_ERROR	Unexpected runtime failure or abort.
2	ExitCode.USAGE_ERROR	CLI usage error (missing/bad arguments).
66	ExitCode.INPUT_MISSING	Required input was missing or unreadable.
69	ExitCode.UNAVAILABLE	Service or dependency unavailable.
78	ExitCode.CONFIG_ERROR	Configuration or environment problem.

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.