Skip to main content

atmos list editions

Use this command to list the editions journal: every change to a previously shipped default, with the date it changed, the old and new values, and a description of the change. Use --from and --to to diff two editions and see exactly which defaults differ between them.

Experimental
atmos list editions --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 list editions [flags]

Description​

Atmos journals every change to a previously shipped default. The atmos list editions command displays that journal, newest first, where each row shows:

  • Date — the day the default changed
  • Key — the configuration key whose default changed
  • Old — the default before the change (what an earlier-pinned project gets)
  • New — the default after the change
  • Description — what the change means in practice

This command is useful for:

  • Deciding which edition to pin your project to
  • Reviewing what changes when you unpin (or move your pin forward): atmos list editions --from=<pin>
  • Diffing two editions before an upgrade: atmos list editions --from=<old> --to=<new>

Flags​

--from string
Show only changes after this edition anchor. Anchors accept YYYY, YYYY-MM, or YYYY-MM-DD; partial dates round to the end of the period they name.
--to string
Show only changes up to and including this edition anchor. Same anchor formats as --from.
--format, -f string
Output format: table, json, yaml, csv, tsv (default: table)

Examples​

List every journaled default change:

atmos list editions

Diff two editions — show only the default changes that took effect between the 2025 and 2026 editions:

atmos list editions --from=2025 --to=2026

Answer "what changes if I unpin?" — show everything that changed after your current pin:

atmos list editions --from=2025-09

Output in machine-readable formats:

atmos list editions --format=json
atmos list editions --format=yaml
atmos list editions --format=csv

Example Output​

> atmos list editions

 Date        Key                            Old          New          Description
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 2026-07-17  describe.component.filter      full         schema       Component descriptions show only stack-manifest sections; set the filter to full for computed internals.
 2026-07-16  describe.provenance            false        true         Component descriptions include provenance annotations (which stack file set each value) by default.
 2026-07-13  list.error_mode                strict       warn         List commands substitute (computed) for unresolved YAML function values and continue instead of aborting.
 2026-07-13  describe.error_mode            strict       warn         Describe commands substitute (computed) for unresolved YAML function values and continue instead of aborting.
 2026-07-06  settings.terminal.help.filter  false        true         Bare --help shows a focused view without the GLOBAL FLAGS section; --help=all prints the full output.
 2026-02-10  components.helmfile.use_eks    true         false        Helmfile EKS integration is opt-in; kubeconfig is no longer downloaded automatically before Helmfile commands.
 2025-12-06  stacks.inherit.metadata        false        true         Component metadata is inherited from base components like vars and settings; previously metadata was per-component only.
 2025-10-16  settings.terminal.pager        true         false        The built-in pager is disabled by default; long output prints directly to the terminal.
 2025-09-23  logs.level                     Info         Warning      The default log level is Warning; informational log messages are hidden unless requested.
 2025-02-11  logs.file                      /dev/stdout  /dev/stderr  Logs are written to stderr so they never contaminate pipeable command output on stdout.

10 default changes journaled. Pin with `edition:` in atmos.yaml.
tip

Use atmos describe edition to see which of these changes an active pin actually rolls back for your project.

See Also​