﻿---
title: changelog add
description: Create a changelog file that describes a single item in the release documentation. For details and examples, go to Add changelog entries. 
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/cli/release/changelog-add
---

# changelog add
Create a changelog file that describes a single item in the release documentation.
For details and examples, go to [Add changelog entries](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/contribute/changelog).

## Usage

```sh
docs-builder changelog add [options...] [-h|--help]
```


## Options

<definitions>
  <definition term="--action <string?>">
    Optional: What users must do to mitigate.
  </definition>
  <definition term="--areas <string[]?>">
    Optional: Areas affected (comma-separated or specify multiple times).
  </definition>
  <definition term="--config <string?>">
    Optional: Path to the changelog.yml configuration file. Defaults to `docs/changelog.yml`.
  </definition>
  <definition term="--description <string?>">
    Optional: Additional information about the change (max 600 characters).
  </definition>
  <definition term="--feature-id <string?>">
    Optional: Feature flag ID
  </definition>
  <definition term="--highlight <bool?>">
    Optional: Include in release highlights.
  </definition>
  <definition term="--impact <string?>">
    Optional: How the user's environment is affected.
  </definition>
  <definition term="--issues <string[]?>">
    Optional: Issue numbers (comma-separated or specify multiple times).
  </definition>
  <definition term="--output <string?>">
    Optional: Output directory for the changelog fragment. Defaults to current directory.
  </definition>
  <definition term="--owner <string?>">
    Optional: GitHub repository owner (used when `--pr` is just a number).
  </definition>
  <definition term="--products <List<ProductInfo>>">
    Required: Products affected in format "product target lifecycle, ..." (for example, `"elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"`).
  </definition>
  <definition term="The valid product identifiers are listed in products.yml.">
  </definition>
  <definition term="The valid lifecycles are listed in ChangelogConfiguration.cs.">
  </definition>
  <definition term="--pr <string?>">
    Optional: Pull request URL or number (if `--owner` and `--repo` are provided).
  </definition>
  <definition term="If specified, --title can be derived from the PR.">
  </definition>
  <definition term="If mappings are configured, --areas and --type can also be derived from the PR.">
  </definition>
  <definition term="--repo <string?>">
    Optional: GitHub repository name (used when `--pr` is just a number).
  </definition>
  <definition term="--subtype <string?>">
    Optional: Subtype for breaking changes (for example, `api`, `behavioral`, or `configuration`).
  </definition>
  <definition term="The valid subtypes are listed in ChangelogConfiguration.cs.">
  </definition>
  <definition term="--title <string>">
    A short, user-facing title (max 80 characters)
  </definition>
  <definition term="Required if --pr is not specified.">
  </definition>
  <definition term="If both --pr and --title are specified, the latter value is used instead of what exists in the PR.">
  </definition>
  <definition term="--type <string>">
    Required: Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`).
  </definition>
  <definition term="The valid types are listed in ChangelogConfiguration.cs.">
  </definition>
</definitions>