Version History & Rollback

Every file write is automatically tracked with an immutable version history. You can view, restore, and roll back files at any time - no manual snapshots needed.

Tools

file_versions

List the version history of any file. Shows version numbers, timestamps, sizes, and sources.

file_versions({ path: "src/index.html" })

file_version_restore

Switch a file to any version - older or newer. No data is lost; all versions are preserved.

file_version_restore({ path: "src/index.html", version: 2 })

rollback

Restore files and folders under a path to their state at a given point in time. Supports scoping to a specific directory and recursive/non-recursive modes.

rollback({ datetime: "2026-04-08T14:30:00Z" })                          // entire project
rollback({ datetime: "2026-04-08T14:30:00Z", path: "src/components" })  // one folder, recursive
rollback({ datetime: "2026-04-08T14:30:00Z", path: "src", recursive: false })  // direct children only
rollback({ datetime: "latest" })                                                // undo previous rollback

How It Works

• Every file write creates an immutable version with a timestamp
• file_version_restore switches which version is active - all versions are preserved
• rollback derives the project state at any point in time from the version history
• Rollback handles both files (version-based) and folders (timestamp-based)
• Files created after the target time are removed; files that existed are restored
• All operations are wrapped in a transaction - atomic and safe

When to Use

• User says "undo that" → use file_versions + file_version_restore for one file
• User says "go back to before I changed everything" → use rollback with a datetime
• Something broke after a series of changes → rollback to before the changes
• Compare what changed → file_versions shows the full timeline per file

Retention policy (how long history is kept — and billed)

Version history is not kept forever. Each account has a retention policy with two bounds, and a version is pruned when it hits either one first:

• Age — versions older than N days are dropped.
• Copies — only the newest M versions of each file are kept.

The current version of every file is always kept, no matter how old — retention only trims old history, never live content, so a file you haven't touched in months is never lost.

Retention is enforced once a day by a cleanup pass that runs right before the storage meter, so the account is billed on its post-cleanup footprint. Storage is billed on physical bytes (retained versions included), so keeping less history costs less.

Defaults and limits (per plan)

• Free: 3 days / 10 copies.
• Pro: 90 days / 100 copies.

The plan sets the maximum a user may keep (and the default when they subscribe). A user can dial their own retention down from that cap to store less and pay less — never above the plan cap.

Telling the user their current policy

Use get_user_info — its Profile section reports the effective retention (e.g. "3 days / 10 copies kept (whichever comes first), plan max 3 days / 10 copies") and flags it [custom] when the user set their own value. That's how to answer "what's my version retention?" or "how long are my old versions kept?".

Seeing what's using the space

When an account is at or over its storage quota, find out where the space went before suggesting anything:

• Local CLI / WebCLI: storage usage — billed bytes against the quota, the live-vs-version-history split, how much deduplication saved, and the biggest projects. Add --json for a machine-readable form.
• API: GET /users/me/storage.

Two figures matter and they are not the same. Billed is physical bytes: retained versions included, deduplicated blobs counted once — that's what the quota is enforced against. Live is just the current version of each file. A big gap between them means version history (or a large retention setting), not live content, is what's filling the account — so trimming retention is the fix, not deleting files.

Per-project numbers are live bytes only: dedup and history can't be attributed to a single project, so they won't sum to the billed total.

When the account is over quota

An over-quota write fails with a storage-quota error. Freeing space always works: delete files that are no longer needed, or keep less history (below). Upgrading only helps if the user's plan isn't already the one with the largest storage grant — credit packs do not raise the storage cap, so telling a top-plan user to buy credits is a dead end. The error text itself only suggests an upgrade when a bigger plan actually exists; follow its lead rather than reflexively recommending a purchase.

Changing it

Retention is a user-owned account setting — don't change it silently on their behalf. Explain the trade-off (less history = smaller storage bill, but shorter rollback reach) and point them at a surface that edits it:

• Local CLI / WebCLI: storage retention (view), storage retention --days <n> --count <n> (set), storage retention --reset (back to the plan default).
• Monitor dashboard: the Files tab shows the policy with editable day/copy fields.
• API: GET /users/me/retention (view) and PATCH /users/me/retention { days, count } (adjust; a value above the plan cap is rejected, null resets a field to the plan default).