---
title: changelog add cli command
description: Create a new changelog entry YAML file. 
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/cli/changelog/add
products:
  - Elastic Docs Builder
---

# changelog add cli command
```bash
docs-builder changelog add [options]
```

Create a new changelog entry YAML file.

## Options

<definitions>
  <definition term="--products string">
    Optional: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"). If not specified, will be inferred from repository or config defaults.
  </definition>
  <definition term="--action string">
    Optional: What users must do to mitigate
  </definition>
  <definition term="--areas string[]">
    Optional: Area(s) affected (comma-separated or specify multiple times)
    **Repeatable:** pass `--areas` multiple times to supply more than one value
  </definition>
  <definition term="--[no-]concise">
    Optional: Omit schema reference comments from generated YAML files. Useful in CI to produce compact output.
    **Default:** `false`
  </definition>
  <definition term="--config string">
    Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml'
    **Constraints:** symbolic links not allowed, must exist, extensions: yml, yaml, supports `~` home expansion
  </definition>
  <definition term="--description string">
    Optional: Additional information about the change (max 600 characters)
  </definition>
  <definition term="--[no-]no-extract-release-notes">
    Optional: Turn off extraction of release notes from PR descriptions. By default, release notes are extracted when using --prs. Matched release note text is used as the changelog description (only if --description is not explicitly provided). The changelog title comes from --title or the PR title, not from the release note section.
    **Default:** `false`
  </definition>
  <definition term="--[no-]no-extract-issues">
    Optional: Turn off extraction of linked references. When using --prs: turns off extraction of linked issues from the PR body (e.g., "Fixes #123"). When using --issues: turns off extraction of linked PRs from the issue body (e.g., "Fixed by #123"). By default, linked references are extracted in both cases.
    **Default:** `false`
  </definition>
  <definition term="--feature-id string">
    Optional: Feature flag ID
  </definition>
  <definition term="--[no-]highlight">
    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 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. Each occurrence can be either comma-separated issues (e.g., `--issues "https://github.com/owner/repo/issues/123,456"`) or a file path (e.g., `--issues /path/to/file.txt`). If --owner and --repo are provided, issue numbers can be used instead of URLs. If specified, --title can be derived from the issue. Creates one changelog file per issue. Mutually exclusive with --release-version and --report.
    **Repeatable:** pass `--issues` multiple times to supply more than one value
  </definition>
  <definition term="--owner string">
    Optional: GitHub repository owner (used when --prs or --issues contains just numbers, or when using --release-version). Falls back to bundle.owner in changelog.yml when not specified. If that value is also absent, "elastic" is used.
  </definition>
  <definition term="--output string">
    Optional: Output directory for the changelog. Falls back to bundle.directory in changelog.yml when not specified. Defaults to current directory.
  </definition>
  <definition term="--prs string[]">
    Optional: Pull request URL(s) or PR number(s) (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers. Can be specified multiple times. Each occurrence can be either comma-separated PRs (e.g., `--prs "https://github.com/owner/repo/pull/123,6789"`) or a file path (e.g., `--prs /path/to/file.txt`). When specifying PRs directly, provide comma-separated values. When specifying a file path, provide a single value that points to a newline-delimited file. If --owner and --repo are provided, PR numbers can be used instead of URLs. If specified, --title can be derived from the PR. If mappings are configured, --areas and --type can also be derived from the PR. Creates one changelog file per PR. Mutually exclusive with --release-version and --report.
    **Repeatable:** pass `--prs` multiple times to supply more than one value
  </definition>
  <definition term="--report string">
    Optional: URL or file path to a promotion report HTML document. Extracts GitHub pull request URLs and creates one changelog per PR (same parsing as `changelog bundle --report`). Mutually exclusive with --prs, --issues, and --release-version.
  </definition>
  <definition term="--release-version string">
    Optional: GitHub release tag to fetch PRs from (e.g., "v9.2.0" or "latest"). When specified, creates one changelog per PR in the release notes. Requires --repo (or bundle.repo in changelog.yml). Mutually exclusive with --prs, --issues, and --report. Does not create a bundle; use 'changelog gh-release' for that.
  </definition>
  <definition term="--repo string">
    Optional: GitHub repository name (used when --prs or --issues contains just numbers, or when using --release-version). Falls back to bundle.repo in changelog.yml when not specified.
  </definition>
  <definition term="--[no-]strip-title-prefix">
    Optional: When used with --prs or --report, remove square brackets and text within them from the beginning of PR titles, and also remove a colon if it follows the closing bracket (e.g., "[Inference API] Title" becomes "Title", "[ES|QL]: Title" becomes "Title", "Discover][ESQL] Title" becomes "Title")
    **Default:** `false`
  </definition>
  <definition term="--subtype string">
    Optional: Subtype for breaking changes (api, behavioral, configuration, etc.)
  </definition>
  <definition term="--title string">
    Optional: A short, user-facing title (max 80 characters). Required if neither --prs, --issues, nor --report is specified. If --prs and --title are specified, the latter value is used instead of what exists in the PR.
  </definition>
  <definition term="--type string">
    Optional: Type of change (feature, enhancement, bug-fix, breaking-change, etc.). Required if neither --prs, --issues, nor --report is specified. If mappings are configured, type can be derived from the PR or issue.
  </definition>
  <definition term="--[no-]use-pr-number">
    Optional: Use PR numbers for filenames instead of timestamp-slug. With --prs, --report, or --issues (where PRs are resolved), each changelog filename will be derived from its PR numbers. Requires --prs, --report, or --issues. Mutually exclusive with --use-issue-number.
    **Default:** `false`
  </definition>
  <definition term="--[no-]use-issue-number">
    Optional: Use issue numbers for filenames instead of timestamp-slug. With both --prs (which creates one changelog per specified PR) and --issues (which creates one changelog per specified issue), each changelog filename will be derived from its issues. Requires --prs or --issues. Mutually exclusive with --use-pr-number.
    **Default:** `false`
  </definition>
  <definition term="-l --log-level enum">
    Minimum log level.
    **Values:** trace, debug, information, warning, error, critical, none
    **Default:** `information`
  </definition>
  <definition term="-c --config-source enum">
    Override the configuration source: local, remote
    **Values:** local, remote, embedded
  </definition>
  <definition term="--[no-]skip-private-repositories">
    Skip cloning private repositories
  </definition>
</definitions>