Configuration

adrs supports multiple configuration methods with the following priority (highest to lowest):

1. Command-line flags
2. Environment variables
3. Project configuration file (adrs.toml, then .adrs.toml, then .adr-dir)
4. Global configuration file (~/.config/adrs/config.toml)
5. Default values

Project Configuration

Legacy Format (.adr-dir)

For compatibility with adr-tools, adrs reads the .adr-dir file:

doc/adr

This single-line file specifies the directory where ADRs are stored.

TOML Format (adrs.toml)

For more options, use adrs.toml in your project root. If adrs.toml is not present, adrs also reads .adrs.toml (same format). When both files exist, adrs.toml is used and a warning: is printed on stderr naming the file that was picked (the same convention as unrecognized keys in the TOML). MCP run_doctor returns that same string in config_warnings.

adrs init --ng writes adrs.toml. To use the hidden filename, create .adrs.toml or rename adrs.toml; init never writes .adrs.toml.

# ADR storage directory (relative to project root)
adr_dir = "doc/adr"

# Operation mode: "compatible" or "nextgen"
# - compatible: adr-tools compatible output (default)
# - nextgen: YAML frontmatter with enhanced features
mode = "compatible"

# Default status for newly created ADRs
# If omitted, defaults to "proposed"
default_status = "proposed"

# Skip opening the editor when creating a new ADR (for CI/scripting)
# If omitted, defaults to false
no_edit = false

# Generate command configuration
[generate]
# Default prefix for TOC links (used by 'adrs generate toc' if --prefix is not given)
# Useful for CI jobs that always regenerate the TOC with the same prefix.
# If omitted, defaults to empty string (bare filename links)
# toc_prefix = "./"

# Export command configuration
[export]
# Default base URL for source_uri fields in JSON export
# (used by 'adrs export json' if --base-url is not given)
# If omitted, defaults to none (no source_uri fields)
# base_url = "https://github.com/org/repo/blob/main/doc/adr"

# Doctor command configuration
[doctor]
# Rule IDs or rule names to suppress permanently (matched case-insensitively).
# '--ignore' flags on the command line merge with this list, they do not replace it.
# If omitted, defaults to an empty list (no rules suppressed)
# ignore = ["ADR011"]

# When true, 'adrs doctor' exits with status 1 if there are warnings, not just errors.
# '--warnings-as-errors' on the command line ORs with this setting.
# If omitted, defaults to false
# warnings_as_errors = false

# Suppress rules for records matching a glob, instead of repository-wide.
# Use this when one record trips a rule you want kept everywhere else.
# 'glob' is matched against each record's path relative to the project root.
# Repeat the block for more than one exemption.
# [[doctor.ignore_path]]
# glob = "doc/adr/0025-*.md"
# rules = ["ADR014"]

# Template configuration
[templates]
# Default format: "nygard" or "madr"
format = "nygard"

# Default variant: "full", "minimal", "bare", or "bare-minimal"
variant = "full"

# Path to custom template file (optional)
# custom = "templates/custom.md"

Global Configuration

Create ~/.config/adrs/config.toml for user-wide defaults:

# Default mode for new repositories
mode = "nextgen"
default_status = "accepted"

[templates]
format = "madr"
variant = "minimal"

Project configuration overrides global configuration.

Environment Variables

Example:

export ADR_DIRECTORY="decisions"
adrs new "Use Redis for caching"

Configuration Discovery

When you run an adrs command, it searches for configuration by:

1. Looking in the current directory for a project config, in this order: adrs.toml, then .adrs.toml, then .adr-dir
2. Searching parent directories up to the git root (or filesystem root), using that same filename order at each directory
3. Checking the global config at ~/.config/adrs/config.toml
4. Using defaults if nothing is found

This means you can run adrs commands from any subdirectory of your project.

Modes

Compatible Mode (default)

Produces output identical to adr-tools:

• Status in the document body
• Links as markdown text
• No YAML frontmatter

NextGen Mode

Enables enhanced features:

• YAML frontmatter for metadata
• Structured status and links
• MADR 4.0.0 fields (decision-makers, consulted, informed)

Enable with --ng flag or in configuration:

mode = "nextgen"

Show Current Configuration

adrs config

Output:

Project root: /path/to/project
Config source: adrs.toml
ADR directory: doc/adr
Full path: /path/to/project/doc/adr
Mode: Compatible