# Scrivener Snapshots

> When the user wants to version a Scrivener document — capture a revertible copy before rewriting, list earlier versions, or roll a document back. Use when the user says "snapshot this", "save a version", "show previous versions", "roll back this document", "compare versions", or "I want to be able to undo this rewrite later". For editing a document's text/structure (which auto-snapshots first), see scrivener-edit. For validating/backing up the whole package, see scrivener-integrity.

- Skill: `donnfelker/scrivener-snapshots` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add donnfelker/scrivener-snapshots`
- Raw SKILL.md: https://api.skillmd.com/api/skills/donnfelker/scrivener-snapshots/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: donnfelker (https://skillmd.com/u/donnfelker)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/donnfelker/scrivener-snapshots

---


# Scrivener snapshots

You help the writer **version a single document**. A snapshot is a captured copy of one
document's text taken at a point in time, stored inside the project so the writer can
look back at — and (on the roadmap) restore — an earlier draft. Snapshots are
per-document and live next to that document's content; they are **not** the same as a
whole-project backup (that is `scrivener-integrity`).

Use this skill when the writer wants a safety net before a rewrite, asks what older
versions exist, or wants to roll a document back to how it was.

## When to reach for a snapshot

- **Before a risky rewrite** — capture the current text so the change is revertible.
- **To see history** — list the snapshots already taken for a document.
- **To roll back** — return a document to an earlier captured version (🔜 planned; see
  the safety note below for what to do today).

## The two things you can do today

### List a document's snapshots — `snapshots <id>`

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py snapshots <uuid> \
  --project "<path.scriv>"
```

Returns each snapshot for that document (title + timestamp). Use this to answer "what
previous versions do I have?" and to find the snapshot a later read/diff/restore would
target.

### Take a snapshot — `snapshot <id> [--title …]`

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py snapshot <uuid> \
  --title "Before tightening the open" \
  --project "<path.scriv>"
```

Captures the document's current `content.rtf` as a new snapshot. Give it a `--title` so
the writer can recognise it later; without one it is identified by its timestamp.

> Note the command names: **`snapshots`** (plural) *lists*; **`snapshot`** (singular)
> *takes*. Both address the document by **UUID** — titles are not unique, so resolve an
> ambiguous title to a UUID first (use `find`/`outline` from scrivener-inspect).

## Auto-snapshot is the safety net (you usually get this for free)

The write skills **automatically take a snapshot of a document before they overwrite its
text** — so an edit is revertible even if the writer never asked for a snapshot.

- `set-text` (and any content-overwriting edit) snapshots first by default.
- Pass `--no-snapshot` only when you deliberately do *not* want the safety copy.
- **Existing snapshots are preserved on every edit** — writes never discard prior
  versions; they only add to the history.

So in practice you rarely *need* a manual `snapshot` before an edit — but taking one with
a clear `--title` is good when the writer wants a named, recognisable checkpoint ("the
version we showed the editor") rather than an auto-generated one.

## Where snapshots live

Each document's snapshots are stored under that document's own data directory:

```
<Project>.scriv/Files/Data/<UUID>/snapshots/
```

Captured as the title + timestamp + the RTF of the captured text. They sit next to
`content.rtf`, so they travel with the project and are included in a project backup. Full
storage detail and format notes: **[references/snapshots.md](references/snapshots.md)**.

## Restoring or comparing — what to do today

`snapshot read`, `snapshot diff`, and `snapshot restore` are on the roadmap but **not yet
in the CLI**. Until they land, to roll a document back:

1. **Back up the whole project first** (`backup`, via scrivener-integrity) — restoring is
   a destructive content change.
2. Locate the target version with `snapshots <id>`.
3. There is no in-CLI restore yet, so treat this as a destructive `set-text` once the
   snapshot's text is available, and rely on the auto-snapshot-before-edit safety so the
   pre-restore state is itself captured.

Be honest with the writer that read/diff/restore are planned (see **Toolkit support**),
and prefer the available commands plus a fresh project backup in the meantime.

## Safety

- **Close the project in Scrivener first**, and let cloud sync (Dropbox/iCloud) finish
  before taking snapshots or editing — a `.scriv` touched mid-sync can conflict.
- Writes **auto-snapshot** a document before overwriting its text (skip with
  `--no-snapshot`) and **preserve existing snapshots** on every edit.
- Address documents by **UUID** when a title is ambiguous — titles are not unique.
- A document legitimately may have **no snapshots** (and many never-edited docs won't) —
  an empty list is normal, not an error.

## Toolkit support

- ✅ `snapshots <id>` — list a document's snapshots (title + timestamp).
- ✅ `snapshot <id> [--title …]` — take a snapshot of the document's `content.rtf`.
- ✅ auto-snapshot-before-edit — the write skills snapshot before overwriting text
  (unless `--no-snapshot`); existing snapshots are preserved on every edit.
- 🔜 `snapshot read <id> <snap>` — read a captured version's text (planned).
- 🔜 `snapshot diff <id> <snap>` — compare a snapshot to current text (planned).
- 🔜 `snapshot restore <id> <snap>` — roll a document back to a snapshot (planned).

## Related skills

- **scrivener-edit** — add/move/rename and edit text; auto-snapshots a document before
  overwriting its `content.rtf` (unless `--no-snapshot`).
- **scrivener-integrity** — `verify`, `repair`, and whole-project `backup`/`restore`;
  back up the project before any rollback.
- **scrivener-format** — where `snapshots/` sits in the `.scriv` package and how content
  is stored.
- **scrivener-inspect** — `outline`/`find` to resolve a title to the UUID a snapshot
  command needs.