---
title: Version
description: blume version freezes the current docs as an archived version — copying the tree, rewriting its links, and registering the id in your config.
---

`blume version` is how you cut a [documentation version](/docs/content/versioning). Give it an id and it freezes the current content tree as a snapshot that keeps serving as the docs were:

```bash
blume version v1.0
```

That does four things:

1. **Copies the content tree** into a folder named after the id (`docs/v1.0/`), leaving existing snapshots out of the copy.
2. **Rewrites root-absolute links inside the copy** so they stay within the snapshot: `/guides/x` becomes `/v1.0/guides/x`. Fenced and inline code are left untouched, and links to pages the snapshot has no copy of — generated API references, remote sources like a changelog — keep pointing at the live pages.
3. **Registers the id** in `versions.archived` in `blume.config.ts`. The first cut turns versioning on, adding a `versions` block with the id archived and the live docs labeled "Latest". When the config is shaped in a way it won't edit, it warns and prints the entry to paste instead.
4. **Reports what it did**: the files copied, the pages whose links were rewritten, and a reminder that archived versions are frozen and that `blume dev` needs a restart to pick the snapshot up.

Review and commit the new folder like any other content. Everything about how versions render — the switcher, the notice on archived pages, per-version labels and badges — is configuration, covered on the [Versioning](/docs/content/versioning) page.

## Listing versions

Run it with no id to list the configured versions: the current one with its label and badge, then each archived id and its folder. Before the first cut, when `versions` isn't configured, it tells you how to cut one instead.

```bash
blume version
```

## Flags

- `--force` — overwrite a snapshot folder that already exists. Without it, an existing folder is an error, so a stray re-run can't clobber an archived version.

## When it refuses

The command exits non-zero without touching anything when:

- the id doesn't start with a letter or contains characters other than letters, digits, dots, hyphens, and underscores (`v1.0`, not `1.0`, so an id can never collide with a [numeric ordering prefix](/docs/content/navigation#ordering));
- the project has error diagnostics, since a snapshot of a broken tree would freeze the breakage — fix them first (`blume doctor` lists them);
- the id is already registered in `versions.archived`;
- the snapshot folder exists and `--force` wasn't passed.