---
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/3809/cli/changelog/remove
products:
  - Elastic Docs Builder
---

# changelog remove cli command
<cli-modifiers>
</cli-modifiers>

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

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/3809/cli/changelog/bundle) to determine which changelogs to remove.
- **Option-based**: `docs-builder changelog remove --products "..."` (or `--prs`, `--issues`, `--all`, `--release-version`, `--report`, `--files`) — specify the filter directly.

Bundles are self-contained (every entry is embedded inline), so removing changelog source files never affects existing bundles or the `{changelog}` directive. The command deletes matching files without any bundle dependency check.
For more context, go to [Bundle changelogs > Remove changelog files](/elastic/docs-builder/pull/3809/data/release-notes/bundle#changelog-remove).
**Behaviour flags:**
`--dry-run` — Print the files that would be removed without deleting them. 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, URL list file, or changelog path list file when also providing a version. When provided, the second argument must be a version string and this is the 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, --report, or --files.
    **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
  </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
  </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="--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="--files string[]">
    Filter by changelog YAML paths (comma-separated), or a path to a newline-delimited file containing changelog paths. Can be specified multiple times. Not supported in profile-based commands; pass a path list file as a positional argument instead.
    **Repeatable:** pass `--files` 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, --issues, and --files.
  </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>


## Global Options

<definitions>
  <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.

| 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             |

Setting `bundle.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`, `--report`, or `--files`.
```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

# Remove an explicit list of changelog files
docs-builder changelog remove --files "./docs/changelog/a.yaml,./docs/changelog/b.yaml" --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/3809/data/release-notes/bundle#changelog-remove) for examples.