Skip to main content

atmos describe edition

Use this command to show whether the project is pinned to an edition (a date anchor for defaults), where the pin came from, the resolved anchor date, and every default the pin keeps at its pre-change value.

Experimental
atmos describe edition --help
Pin Your Project to an Edition

Learn how to pin your project's defaults to a date anchor with the top-level edition setting in your atmos.yaml.

Usage​

atmos describe edition [flags]

Description​

The atmos describe edition command reports the effect of the active edition pin:

  • pinned — whether an edition is set at all
  • edition — the raw pin as you wrote it (e.g. 2025-09)
  • resolved_date — the fully resolved anchor date (partial dates round to the end of the period they name)
  • granularity — how much of the date the pin specified: year, month, or day
  • source — where the pin came from: flag (--edition), env (ATMOS_EDITION), or config (atmos.yaml)
  • overrides — every default the pin rolls back, with the pinned (effective) value, the latest default you would get by unpinning, and the journal entries behind the change

Without a pin, it reports pinned: false with no overrides — the project follows the latest defaults.

Flags​

--format, -f string
Output format: yaml or json (default: yaml)

Examples​

Show the active pin and its effect:

atmos describe edition

Output as JSON:

atmos describe edition --format=json

Preview the effect of a pin without changing your configuration, using the --edition global flag:

atmos --edition=2026-01 describe edition

Example Output​

atmos describe edition
pinned: true
edition: 2026-06
resolved_date: "2026-06-30"
granularity: month
source: config
overrides:
    - key: describe.component.filter
      kind: value
      from_value: full
      to_value: schema
      entries:
        - date: "2026-07-17"
          key: describe.component.filter
          kind: value
          old: full
          new: schema
          description: Component descriptions show only stack-manifest sections; set the filter to full for computed internals.
          ref: https://atmos.tools/changelog/config-editions
    - key: describe.error_mode
      kind: value
      from_value: strict
      to_value: warn
      entries:
        - date: "2026-07-13"
          key: describe.error_mode
          kind: value
          old: strict
          new: warn
          description: Describe commands substitute (computed) for unresolved YAML function values and continue instead of aborting.
          ref: https://atmos.tools/changelog/list-describe-graceful-degradation
    - key: describe.provenance
      kind: value
      from_value: false
      to_value: true
      entries:
        - date: "2026-07-16"
          key: describe.provenance
          kind: value
          old: false
          new: true
          description: Component descriptions include provenance annotations (which stack file set each value) by default.
          ref: https://atmos.tools/changelog/config-editions
    - key: list.error_mode
      kind: value
      from_value: strict
      to_value: warn
      entries:
        - date: "2026-07-13"
          key: list.error_mode
          kind: value
          old: strict
          new: warn
          description: List commands substitute (computed) for unresolved YAML function values and continue instead of aborting.
          ref: https://atmos.tools/changelog/list-describe-graceful-degradation
    - key: settings.terminal.help.filter
      kind: value
      from_value: false
      to_value: true
      entries:
        - date: "2026-07-06"
          key: settings.terminal.help.filter
          kind: value
          old: false
          new: true
          description: Bare --help shows a focused view without the GLOBAL FLAGS section; --help=all prints the full output.
          ref: https://github.com/cloudposse/atmos/pull/2696

In each override, from_value is the default your pinned project actually uses, and to_value is the latest default the project would get by unpinning.

tip

Use atmos list editions to browse the full journal of default changes, or to diff two editions with --from and --to.

See Also​