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

Browse the complete [edition history](/cli/editions) online, including the old and new values and source for every change.

> ⚠️ Experimental

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

Configuration Reference[Read more](/cli/configuration/edition)

## Usage

```shell
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, or the identifier of a behavior transition
- **Old** — the previous default or behavior (what an earlier-pinned project gets)
- **New** — the new default or behavior
- **Description** — what the change means in practice

This command is useful for:

- Deciding which [`edition`](/cli/configuration/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:

```shell
atmos list editions
```

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

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

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

```shell
atmos list editions --from=2025-09
```

Output in machine-readable formats:

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

## Edition History

Browse the complete [edition history](/cli/editions) on the website. It is generated from the same journal
used by this command. Run `atmos list editions` to see the entries included in your installed Atmos version.

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

## See Also

- [`edition` configuration](/cli/configuration/edition) — Pin your project's defaults to a date anchor
- [`atmos describe edition`](/cli/commands/describe/edition) — Show the active pin and every default it rolls back