---
title: changelog note cli command
description: Create a changelog note file for an item that applies to one or more specific release versions and has no associated pull request. Notes are used for...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3941/cli/changelog/note
products:
  - Elastic Docs Builder
---

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

Create a changelog note file for an item that applies to one or more specific release versions and has no associated pull request.
Notes are used for known issues, security advisories, and other items that are not tied to a single PR.
For details and examples, go to [Create changelogs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3941/data/release-notes/create).
Note files are named `note-{slug}.yml` and are uploaded to the changelog pool like any other entry.
Each note declares `products[].versions` — the release versions it applies to — instead of deriving its release line from a branch.

## Options

<definitions>
  <definition term="--name string">
    Explicit slug for the note filename. Defaults to a slug derived from the title.
  </definition>
  <definition term="--products string">
    Products and versions in the format `"product versions lifecycle, ..."` where `versions` is a `|`-separated list of release versions (for example, `"elasticsearch 9.3.0|9.4.0 ga"`).
    Unlike `changelog add`, the middle slot is interpreted as a `|`-separated version list, not a single target.
    The valid product identifiers are listed in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
  </definition>
  <definition term="--action string">
    Optional action text.
  </definition>
  <definition term="--areas string[]">
    Optional area tags.
    **Repeatable:** pass `--areas` multiple times to supply more than one value
  </definition>
  <definition term="--concise">
    Omit schema reference comments from the generated YAML.
    **Default:** `false`
  </definition>
  <definition term="--config string">
    Path to the changelog.yml configuration file.
    **Constraints:** symbolic links not allowed, must exist, extensions: yml, yaml
  </definition>
  <definition term="--description string">
    Additional information about the note (max 600 characters). Optional.
  </definition>
  <definition term="--no-extract-release-notes">
    Skip extracting release note text from PR/issue descriptions.
    **Default:** `false`
  </definition>
  <definition term="--no-extract-issues">
    Skip extracting linked issues/PRs from PR/issue body.
    **Default:** `false`
  </definition>
  <definition term="--feature-id string">
    Optional feature ID.
  </definition>
  <definition term="--highlight">
    Mark the entry as a highlight.
  </definition>
  <definition term="--impact string">
    Optional impact text.
  </definition>
  <definition term="--issues string[]">
    URLs of related issues. Optional citation field; does not determine note addressability.
    **Repeatable:** pass `--issues` multiple times to supply more than one value
  </definition>
  <definition term="--owner string">
    GitHub owner. Falls back to bundle.owner or "elastic".
  </definition>
  <definition term="--output string">
    Output directory.
  </definition>
  <definition term="--prs string[]">
    Optional PR URLs (cited but not used as anchor).
    **Repeatable:** pass `--prs` multiple times to supply more than one value
  </definition>
  <definition term="--repo string">
    GitHub repository name.
  </definition>
  <definition term="--strip-title-prefix">
    Strip a repo-name prefix from the title.
    **Default:** `false`
  </definition>
  <definition term="--strict-fetch">
    Treat GitHub fetch failures as errors.
    **Default:** `false`
  </definition>
  <definition term="--subtype string">
    Entry subtype.
  </definition>
  <definition term="--title string">
    A short, user-facing headline for the note (max 80 characters). Required.
  </definition>
  <definition term="--type string">
    The type of change. For valid values, see [ChangelogEntryType.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntryType.cs). Required.
  </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="--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="--skip-private-repositories">
    Skip cloning private repositories
  </definition>
</definitions>


## Product and version format

The `--products` option uses the same positional format as `changelog add`, but the middle slot is a version list:
- `"elasticsearch 9.3.0 ga"` — one version
- `"elasticsearch 9.3.0|9.4.0|9.5.0 ga"` — multiple versions
- `"cloud-serverless 2025-08-05"` — date-based release, one version

A note that spans products can declare each product separately:
```sh
docs-builder changelog note \
  --title "Known issue with aggregations" \
  --type known-issue \
  --products "elasticsearch 9.3.0|9.4.0 ga" \
  --products "kibana 9.3.0|9.4.0 ga"
```


## Output

The command writes a `note-{slug}.yml` file to the configured output directory.
The file contains `products[].versions` instead of `products[].target`:
```yaml
title: Known issue with aggregations
type: known-issue
products:
  - product: elasticsearch
    versions: [9.3.0, 9.4.0]
    lifecycle: ga
```


## Lifecycle after creation

Notes are uploaded to `changelog/{org}/{repo}/{branch}/note-*.yml` in the private S3 bucket and go through the scrubber exactly like entries.
A Lambda-maintained index at `changelog/{org}/{repo}/notes-{version}.json` lists every note that applies to a given version.
If the release bundle for that version has already shipped when a note is uploaded, the scrubber Lambda automatically generates an amend sidecar (`{bundle}.amend-notes.yaml`) so the note reaches CDN consumers without a manual rerun.

## Configuration checks

The same configuration-file checks that apply to `changelog add` apply here:
valid `products`, `lifecycles`, and `type` values are validated against `docs/changelog.yml` when it exists.
Specifying a version target in `--products` for `changelog add` is an error; use `changelog note` instead.
Conversely, `--versions` has no meaning for `changelog add` — it is note-specific.