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>

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 …]

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.

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.