﻿---
title: changelog add
description: Create a changelog file that describes a single item in the release documentation. For details and examples, go to Create and bundle changelogs. 
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2842/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 [Create and bundle changelogs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2842/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="If the content contains any special characters such as backquotes(`), you must precede it with a backslash escape character (``).">
  </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="If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (\).">
  </definition>
  <definition term="--no-extract-release-notes">
    Optional: Turn off extraction of release notes from PR descriptions.
  </definition>
  <definition term="The extractor looks for content in various formats in the PR description:">
  </definition>
  <definition>
    - `Release Notes: ...`
  </definition>
  <definition>
    - `Release-Notes: ...`
  </definition>
  <definition>
    - `release notes: ...`
  </definition>
  <definition>
    - `Release Note: ...`
  </definition>
  <definition>
    - `Release Notes - ...`
  </definition>
  <definition>
    - `## Release Note` (as a markdown header)
  </definition>
  <definition term="Short release notes (≤120 characters, single line) are used as the changelog title (only if --title is not explicitly provided).">
  </definition>
  <definition term="Long release notes (>120 characters or multi-line) are used as the changelog description (only if --description is not explicitly provided).">
  </definition>
  <definition term="By default, the behavior is determined by the extract.release_notes changelog configuration setting.">
  </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="If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (\).">
  </definition>
  <definition term="--issues <string[]?>">
    Optional: Issue URL(s) or number(s) (comma-separated), or a path to a newline-delimited file containing issue URLs or numbers. Can be specified multiple times.
  </definition>
  <definition term="Each occurrence can be either comma-separated issues (for example --issues "https://github.com/owner/repo/issues/123,456") or a file path (for example --issues /path/to/file.txt).">
  </definition>
  <definition term="When specifying issues directly, provide comma-separated values.">
  </definition>
  <definition term="When specifying a file path, provide a single value that points to a newline-delimited file.">
  </definition>
  <definition term="If --owner and --repo are provided, issue numbers can be used instead of URLs.">
  </definition>
  <definition term="If specified, --title can be derived from the issue.">
  </definition>
  <definition term="Creates one changelog file per issue.">
  </definition>
  <definition term="--no-extract-issues">
    Optional: Turn off extraction of linked references.
  </definition>
  <definition term="When using --prs: turns off extraction of linked issues from the PR body (for example, "Fixes #123").">
  </definition>
  <definition term="When using --issues: turns off extraction of linked PRs from the issue body (for example, "Fixed by #123").">
  </definition>
  <definition term="By default, the behavior is determined by the extract.issues changelog configuration setting.">
  </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 `--prs` or `--issues` contains just numbers).
  </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="--prs <string[]?>">
    Optional: Pull request URLs or numbers (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers. Can be specified multiple times.
  </definition>
  <definition term="Each occurrence can be either comma-separated PRs (for example --prs "https://github.com/owner/repo/pull/123,6789") or a file path (for example --prs /path/to/file.txt).">
  </definition>
  <definition term="When specifying PRs directly, provide comma-separated values.">
  </definition>
  <definition term="When specifying a file path, provide a single value that points to a newline-delimited file.">
  </definition>
  <definition term="If --owner and --repo are provided, PR numbers can be used instead of URLs.">
  </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="Creates one changelog file per PR.">
  </definition>
  <definition term="If there are block ... create definitions in the changelog configuration file and a PR has a blocking label for any product in --products, that PR is skipped and no changelog file is created for it.">
  </definition>
  <definition term="--release-version <string?>">
    Optional: GitHub release tag to use as a source of pull requests (for example, `"v9.2.0"` or `"latest"`).
  </definition>
  <definition term="When specified, the command fetches the release from GitHub, parses PR references from the release notes, and creates one changelog file per PR — without creating a bundle.">
  </definition>
  <definition term="Use docs-builder changelog gh-release instead if you also want a bundle.">
  </definition>
  <definition term="Requires --repo. Mutually exclusive with --prs and --issues.">
  </definition>
  <definition term="Set to latest to use the most recent release.">
  </definition>
  <definition term="--repo <string?>">
    Optional: GitHub repository name (used when `--prs`, `--issues`, or `--release-version` is specified).
  </definition>
  <definition term="--strip-title-prefix">
    Optional: When used with `--prs`, remove square brackets and text within them from the beginning of PR titles, and also remove a colon if it follows the closing bracket.
  </definition>
  <definition term="For example, if a PR title is "[Attack discovery]: Improves Attack discovery hallucination detection", the changelog title will be "Improves Attack discovery hallucination detection".">
  </definition>
  <definition term="Multiple square bracket prefixes are also supported (for example "[Discover][ESQL] Fix filtering by multiline string fields" becomes "Fix filtering by multiline string fields").">
  </definition>
  <definition term="This option applies only when the title is derived from the PR (when --title is not explicitly provided).">
  </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 neither --prs nor --issues is specified.">
  </definition>
  <definition term="If both --prs and --title are specified, the latter value is used instead of what exists in the PR.">
  </definition>
  <definition term="If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (\).">
  </definition>
  <definition term="--type <string>">
    Required if neither `--prs` nor `--issues` is specified. Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`).
  </definition>
  <definition term="If mappings are configured, type can be derived from the PR or issue.">
  </definition>
  <definition term="The valid types are listed in ChangelogConfiguration.cs.">
  </definition>
  <definition term="--use-pr-number">
    Optional: Use the PR number(s) as the filename instead of generating it from a timestamp and title.
  </definition>
  <definition term="With multiple PRs, uses hyphen-separated numbers (for example, 137431-137432.yaml).">
  </definition>
  <definition term="Requires --prs. Mutually exclusive with --use-issue-number.">
  </definition>
  <definition term="--use-issue-number">
    Optional: Use the issue number(s) as the filename instead of generating it from a timestamp and title.
  </definition>
  <definition term="With multiple issues, uses hyphen-separated numbers (for example, 12345-12346.yaml).">
  </definition>
  <definition term="Requires --issues. When both --issues and --prs are specified, still uses the issue number for the filename if this flag is set. Mutually exclusive with --use-pr-number.">
  </definition>
</definitions>

<important>
  `--use-pr-number` and `--use-issue-number` are mutually exclusive; specify only one.
</important>