init

Initialize a new ADR repository.

Usage

adrs init [OPTIONS] [DIRECTORY]

Arguments

Argument	Description
`[DIRECTORY]`	ADR directory path (default: `doc/adr`)

Options

Option	Description
`--ng`	Use NextGen mode (YAML frontmatter)
`-C, --cwd <DIR>`	Working directory
`-h, --help`	Print help

Description

The init command creates:

A configuration file in the current directory: .adr-dir (containing the ADR directory path) in compatible mode, or adrs.toml in NextGen mode (--ng)
The ADR directory (creates parent directories if needed)
An initial ADR: 0001-record-architecture-decisions.md

Examples

Basic Initialization

adrs init

Creates:

.adr-dir          # Contains "doc/adr"
doc/
  adr/
    0001-record-architecture-decisions.md

Custom Directory

adrs init decisions

Creates:

.adr-dir          # Contains "decisions"
decisions/
  0001-record-architecture-decisions.md

NextGen Mode

adrs init --ng

Writes adrs.toml instead of .adr-dir, and creates the initial ADR with YAML frontmatter:

---
number: 1
title: Record architecture decisions
date: 2024-01-15
status: accepted
---

# 1. Record architecture decisions

...

adrs init is idempotent: running it again in an already-initialized repository succeeds. It rewrites the configuration (for example, to change the ADR directory or switch modes) and preserves existing ADRs. The initial "Record architecture decisions" ADR is only created when the repository has no ADRs yet, so re-initializing will not add a duplicate.

config - Show current configuration
new - Create additional ADRs

adrs documentation