Command Reference

init

autochangelog init [--file <path>] [--verbose]

Creates a minimal CHANGELOG.md skeleton at the target path. The file is only written if the destination does not already exist and the parent directory exists. The skeleton is always the same regardless of environment or project context.

Options

• --file <path> Destination path. Default: CHANGELOG.md. Fails if the file already exists. Does not create the parent directory.
• --verbose Emit an operator trace to stderr. Stdout is unaffected.

Skeleton produced

# Changelog

## [Unreleased]

Examples

autochangelog init
autochangelog init --file docs/CHANGELOG.md

Failure modes

• 4File already exists. init does not overwrite.
• 3Parent directory does not exist.
• 3File could not be written (permissions or disk error).

validate

autochangelog validate [<file>] [--format text|json] [--strict] [--require-unreleased] [--allow <RULE_ID>] [--verbose]

Reads the target changelog, runs all active validation rules, and emits a structured report. Never writes or modifies the file. All rules run on every invocation regardless of earlier failures.

Options

• <file> Path to the changelog file. Default: CHANGELOG.md. Positional argument; optional.
• --format text|json Output format. text = human-readable (default). json = schema-bound machine-readable report for CI and downstream automation.
• --strict Treat warnings as failures. Any warning causes exit 1 and passed: false in JSON output.
• --require-unreleased Emit a MISSING_UNRELEASED warning when no [Unreleased] block is present. Under --strict, this causes exit 1.
• --allow <RULE_ID> One-shot severity override for a single Policy rule. Downgrades an Error to Warning for this invocation. Repeatable. Applies to Policy rules only; using --allow on a HardInvariant rule is a usage error (exit 4).
• --verbose Emit an operator trace to stderr. Stdout is unaffected.

Rule policy

Policy rules can be reconfigured without modifying the tool. Two mechanisms are available.

.autochangelog.json — persistent project config placed next to the changelog. Keys are full rule IDs; values are error, warning, or off. CLI overrides take precedence over the config file.

{
  "rules": {
    "Changelog/Validation/UNKNOWN_SECTION": "warning",
    "Changelog/Validation/EMPTY_SECTION": "off"
  }
}

HardInvariant rules — NO_CHANGELOG_STRUCTURE, DUPLICATE_VERSION, DUPLICATE_SECTION, INVALID_DATE, and EMPTY_RELEASE — cannot be suppressed by either mechanism.

Examples

autochangelog validate
autochangelog validate path/to/CHANGELOG.md
autochangelog validate CHANGELOG.md --format json
autochangelog validate CHANGELOG.md --strict
autochangelog validate CHANGELOG.md --format json --strict
autochangelog validate CHANGELOG.md --require-unreleased --strict
autochangelog validate CHANGELOG.md --allow Changelog/Validation/UNKNOWN_SECTION

JSON output

With --format json, the report is machine-readable and schema-backed. Field names and types are stable across the 1.x series and safe to script against in CI and downstream automation.

{
  "autochangelog_version": "1.3.9",
  "file": "CHANGELOG.md",
  "passed": true,
  "strict": false,
  "release_count": 16,
  "has_unreleased": true,
  "errors": [],
  "warnings": [],
  "rule_overrides": {}
}

JSON schema: schemas/autochangelog/validation-report.schema.json in the product repository.

Validation rules

Structural parse checks run first. If any fire, the tool exits with code 2 and no validation rules run.

• MALFORMED_HEADING Parse error A ## [ heading with no closing bracket or an empty identifier.
• DUPLICATE_UNRELEASED Parse error More than one [Unreleased] block found.
• ORPHAN_SECTION Parse error A ### section heading appears outside any release or Unreleased block.
• ORPHAN_ENTRY Parse error A bullet entry appears inside a block but before any section heading.
• BLANK_ENTRY Parse error A bullet entry has no text content after the marker (- or * ).

Validation rules run after a clean parse. Errors cause exit 1 unconditionally. Warnings cause exit 1 only under --strict.

• NO_CHANGELOG_STRUCTURE Error The file contains no [Unreleased] block and no versioned release blocks. Preamble-only content, arbitrary prose, and junk files are unconditionally invalid.
• DUPLICATE_VERSION Error Two or more release blocks with the same version identifier.
• INVALID_DATE Error A release date is present but not in yyyy-MM-dd format.
• UNKNOWN_SECTION Error A section heading is not in the canonical taxonomy: Added, Changed, Deprecated, Removed, Fixed, Security.
• DUPLICATE_SECTION Error Two or more section headings with the same name appear within the same release or Unreleased block.
• EMPTY_RELEASE Error A versioned release block contains no sections. [Unreleased] is explicitly exempt.
• MISSING_DATE Warning A versioned release block has no date.
• NON_SEMVER_VERSION Warning A version identifier does not conform to semver.
• MISSING_UNRELEASED Warning No [Unreleased] block found. Active only when --require-unreleased is passed.
• VERSION_ORDER Warning Releases are not in descending semver order.
• EMPTY_SECTION Warning A section heading is present but contains no entries.
• SECTION_ORDER Warning Sections within a block are not in canonical order: Added, Changed, Deprecated, Removed, Fixed, Security. Fails under --strict.

Failure modes

• 3File not found or could not be read.
• 2File has structural parse errors. Emitted before validation rules run.
• 1One or more validation errors found.
• 1Warnings found and --strict is active.
• 4Invalid --format value or unknown option.

add

autochangelog add --section <section> --message "<text>" [--file <path>] [--version <ver>] [--verbose]

Appends a single bullet entry to the specified section of the target version block. If the section does not exist it is created in canonical order (Added, Changed, Deprecated, Removed, Fixed, Security). If targeting Unreleased and no [Unreleased] block exists, one is created. The file is written only if the result passes validation. If validation would fail, the original file is left untouched.

Options

• --section <section> Required. Case-insensitive. Valid values: Added, Changed, Deprecated, Removed, Fixed, Security.
• --message "<text>" Required. Entry text without the leading bullet. Must not be blank, contain newlines, or start with - or * . Multi-word values require shell quoting.
• --file <path> Path to the changelog file. Default: CHANGELOG.md.
• --version <ver> Target version block. Default: Unreleased. Use a semver string to target an existing release block. Targeting a version that does not exist is an error.
• --verbose Emit an operator trace to stderr. Stdout is unaffected.

Examples

autochangelog add --section Added --message "Support for config file reloading"
autochangelog add --section Fixed --message "Race condition in retry logic"
autochangelog add --section Changed --message "Bump minimum TLS version" --version 1.2.0
autochangelog add --section Security --message "CVE-2026-XXXX patched" --file path/to/CHANGELOG.md

Failure modes

• 4Invalid section name, blank message, or message contains newlines or a bare bullet prefix.
• 3File not found, could not be read, or write failed.
• 2File has structural parse errors.
• 1Target version block does not exist in the changelog.
• 1Rendered result would fail validation. Original file is left untouched.

release

autochangelog release --version <semver> --date <yyyy-MM-dd> [--file <path>] [--verbose]

Cuts a release from the current [Unreleased] block. Moves all entries into a new versioned release block placed immediately below [Unreleased], then recreates an empty [Unreleased] block. The file is written only if the rendered result passes validation. The original file is left untouched if any precondition fails or if validation of the rendered output fails.

Options

• --version <semver> Required. Version string for the new release. Must be valid semver: MAJOR.MINOR.PATCH[-prerelease][+build].
• --date <yyyy-MM-dd> Required. Release date in ISO 8601 format. No default — no automatic date injection.
• --file <path> Path to the changelog file. Default: CHANGELOG.md.
• --verbose Emit an operator trace to stderr. Stdout is unaffected.

Preconditions

The command exits with code 1 if any of the following are not met:

• An [Unreleased] block must exist in the file.
• The [Unreleased] block must contain at least one entry.
• The target version must not already exist in the changelog.

Examples

autochangelog release --version 1.3.0 --date 2026-04-08
autochangelog release --version 2.0.0 --date 2026-06-01 --file path/to/CHANGELOG.md

Failure modes

• 4Invalid semver or invalid date format.
• 3File not found, could not be read, or write failed.
• 2File has structural parse errors.
• 1Precondition not met: no [Unreleased] block, empty [Unreleased], or version already exists.