---
title: changelog remove cli command
description: Remove changelog YAML files from a directory. Two mutually exclusive modes are available: Profile-based: docs-builder changelog remove <profile> <version|promotion-report>...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2736/cli/changelog/remove
products:
  - Elastic Docs Builder
---

# changelog remove cli command
```bash
docs-builder changelog remove \
  [<profile>] \
  [<profile-arg>] \
  [<profile-report>] \
  [options]
```

<cli-modifiers>
</cli-modifiers>

Remove changelog YAML files from a directory.
Two mutually exclusive modes are available:
- **Profile-based**: `docs-builder changelog remove <profile> <version|promotion-report>` — uses the same `bundle.profiles` configuration as [`changelog bundle`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2736/cli/changelog/bundle) to determine which changelogs to remove.
- **Option-based**: `docs-builder changelog remove --products "..."` (or `--prs`, `--issues`, `--all`, `--release-version`, `--report`) — specify the filter directly.

Before deleting anything, the command checks whether any matching files are referenced by unresolved bundles, to prevent silently breaking the `{changelog}` directive.
For more context, go to [Bundle changelogs > Remove changelog files](/elastic/docs-builder/pull/2736/contribute/bundle-changelogs#changelog-remove).
**Behaviour flags:**
`--dry-run` — Print the files that would be removed without deleting them. Valid in both profile and raw mode.
`--force` — Proceed with removal even when files are referenced by unresolved bundles. Emits warnings instead of errors for each dependency. Valid in both profile and raw mode.

## Arguments

<definitions>
  <definition term="<profile> string">
    Optional: Profile name from bundle.profiles in config (for example, "elasticsearch-release"). When specified, the second argument is the version or promotion report URL.
  </definition>
  <definition term="<profile-arg> string">
    Optional: Version number or promotion report URL/path when using a profile (for example, "9.2.0" or "[https://buildkite.../promotion-report.html](https://buildkite.../promotion-report.html)")
  </definition>
  <definition term="<profile-report> string">
    Optional: Promotion report or URL list file when also providing a version. When provided, the second argument must be a version string and this is the PR/issue filter source.
  </definition>
</definitions>


## Options

<definitions>
  <definition term="--[no-]all">
    Remove all changelogs in the directory. Exactly one filter option must be specified: --all, --products, --prs, --issues, or --report.
    **Default:** `false`
  </definition>
  <definition term="--bundles-dir string">
    Optional: Override the directory that is scanned for bundles during the dependency check. Auto-discovered from config or fallback paths when not specified.
    **Constraints:** symbolic links not allowed, supports `~` home expansion
  </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="--directory string">
    Optional: Directory containing changelog YAML files. Uses config bundle.directory or defaults to current directory
    **Constraints:** symbolic links not allowed, supports `~` home expansion
  </definition>
  <definition term="--[no-]dry-run">
    Print the files that would be removed without deleting them. Valid in both profile and raw mode. (preview changes without applying them)
    **Default:** `false`
  </definition>
  <definition term="--[no-]force">
    Proceed with removal even when files are referenced by unresolved bundles. Emits warnings instead of errors for each dependency. Valid in both profile and raw mode. (pass to skip the confirmation prompt)
    **Default:** `false`
  </definition>
  <definition term="--issues string[]">
    Filter by issue URLs (comma-separated) or a path to a newline-delimited file containing fully-qualified GitHub issue URLs. Can be specified multiple times.
    **Repeatable:** pass `--issues` multiple times to supply more than one value
  </definition>
  <definition term="--owner string">
    Optional: GitHub repository owner, which is used when PRs or issues are specified as 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="--products string">
    Filter by products in format "product target lifecycle, ..." (for example, "elasticsearch 9.3.0 ga"). All three parts are required but can be wildcards (*).
  </definition>
  <definition term="--prs string[]">
    Filter by pull request URLs (comma-separated) or a path to a newline-delimited file containing fully-qualified GitHub PR URLs. Can be specified multiple times.
    **Repeatable:** pass `--prs` multiple times to supply more than one value
  </definition>
  <definition term="--release-version string">
    GitHub release tag to use as a filter source (for example, "v9.2.0" or "latest"). Fetches the release, parses PR references from the release notes, and removes changelogs whose PR URLs match — equivalent to passing the PR list using --prs.
  </definition>
  <definition term="--repo string">
    GitHub repository name, which is used when PRs or issues are specified as numbers or when --release-version is used. Falls back to bundle.repo in changelog.yml when not specified. If that value is also absent, the product ID is used.
  </definition>
  <definition term="--report string">
    Optional (option-based mode only): URL or file path to a promotion report. Extracts PR URLs and uses them as the filter. Mutually exclusive with --all, --products, --prs, --release-version, and --issues.
  </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>


## Directory resolution

Both modes use the same ordered fallback to locate changelog YAML files and existing bundles.
**Changelog files directory:**

| Priority | Profile-based                         | Option-based                          |
|----------|---------------------------------------|---------------------------------------|
| 1        | `bundle.directory` in `changelog.yml` | `--directory` CLI option              |
| 2        | Current working directory             | `bundle.directory` in `changelog.yml` |
| 3        | —                                     | Current working directory             |

**Bundles directory** (scanned during the dependency check):

| Priority | Both modes                                     |
|----------|------------------------------------------------|
| 1        | `--bundles-dir` CLI option (option-based only) |
| 2        | `bundle.output_directory` in `changelog.yml`   |
| 3        | `{changelog-dir}/bundles`                      |
| 4        | `{changelog-dir}/../bundles`                   |

Setting `bundle.directory` and `bundle.output_directory` in `changelog.yml` is recommended so you don't need to rely on running the command from a specific directory.

## Option-based examples

Exactly one filter must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version`, or `--report`.
```sh
# Preview what would be removed (dry run)
docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run

# Remove by GitHub release tag
docs-builder changelog remove \
  --release-version v1.34.0 \
  --repo apm-agent-dotnet --owner elastic

# Preview using the latest release
docs-builder changelog remove --release-version latest --dry-run
```

<note>
  `--release-version` requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API.
</note>

The `--products` filter supports wildcards:
- `"elasticsearch 9.3.0 ga"` — exact match
- `"elasticsearch * *"` — all elasticsearch changelogs
- `"* 9.3.* *"` — any product with a target starting with `9.3.`
- `"* * *"` — all changelogs (equivalent to `--all`)


## Profile-based examples

When `changelog.yml` defines `bundle.profiles`, use those same profiles with `changelog remove` to remove exactly the changelogs that would be included in a matching bundle.
Profile-based commands discover the changelog configuration automatically: they look for `changelog.yml` in the current directory, then `docs/changelog.yml`.
Refer to [Bundle changelogs > Remove changelog files](/elastic/docs-builder/pull/2736/contribute/bundle-changelogs#changelog-remove) for examples.