If a run went wrong, or you saved over something good, you can put it back. Reverting works at three levels, warns you when someone has built on the state you are about to overwrite, and captures a version of its own, so you can undo the undo.

## The three levels

| You want to | Use | What happens |
|---|---|---|
| Put one file back to how it was | Restore a version | Monofile saves the current content, then writes that version over it |
| Undo everything one run did | Revert the changeset | Each file goes back to its state before the run started |
| Get rid of a file a run created | Revert the changeset | Monofile deletes the files the run created |

Pick the level that matches the mistake. One bad paragraph in one file is a version restore. "That whole refactor was wrong" is a changeset revert.

## Restoring one file

In the web app, open the file, choose **History** from the tab actions menu, select a version, preview or compare it, press **Restore**, and confirm.

From the terminal, with no `--to` it undoes the most recent change:

```bash title="Terminal"
monofile versions /Projects/report.md
monofile revert /Projects/report.md --to ver_abc123
```

From the API, `revert_file` takes a path and a version id from `list_versions`, and needs the `files:write` scope. Read the old content with `read_version` first to check what you are restoring.

## Reverting a whole run

In the chat, open the review card under the conversation and press **Revert all**. Everywhere else, find the changeset and revert it by id:

```bash title="Terminal"
monofile changesets list --limit 10
monofile changesets revert <changeset-id>
```

The API equivalent is `revert_changeset`, which needs both `files:write` and `files:delete`, because undoing a run can mean deleting the files it created.

## When a file has changed since

Reverting a changeset stops if anything wrote to one of its files after the run did. Another person, another agent, or you in a different tab may have built on the new state, and the guard keeps a revert from throwing that work away.

The refusal is an error with the code `CONFLICT`, and it lists which files changed. In the chat, the review panel shows the same list as an inline banner with a **Force** button. On the CLI and the API you re-run with `--force` or `"force": true`.

> [!WARNING]
> Before you force, read the list. Monofile captures the current content of every file as a version before overwriting it, so a forced revert is itself recoverable. Still check that the work you are about to roll back was not wanted. If an agent asks whether to force, a person should answer.

## Reverting is a write, so it is versioned too

Every restore captures the content it replaces. A file restore adds a "Before revert" entry to that file's history. A changeset revert records all of the pre-revert states together as a new changeset. A revert you regret is one more revert away from fixed, as many times as you need.

## What a revert cannot bring back

- **A deleted file.** Deleting is the one permanent act in Monofile. There is no trash, and a file's history goes with it. Take a [[Checkpoints|checkpoint]] before a delete you are unsure about.
- **A version that has aged out.** Monofile trims automatic versions to the newest 20 per file and never trims checkpoints, so take one before risky work.
- **Media content.** Images and video live in object storage, so replacing one replaces it.

## Next steps

:::cards
- [[Checkpoints]] — Named snapshots of a file or a folder subtree you can return to.
- [[Changesets]] — Runs grouped into one reviewable, revertable unit.
- [[Reviewing Changes]] — The diff view and the changeset card: keep or revert everything an agent touched.
- [[How Versioning Works]] — Automatic version capture on every write, and how long versions last.
:::