A checkpoint is a named snapshot you take on purpose, of one file or of a whole folder subtree. Monofile trims automatic versions as you keep working and never trims checkpoints, so a checkpoint is the marker you can still find next month.

## When to take one

- Before a rewrite you are not sure about, so "start again from before" stays cheap.
- Before you let an agent loose on a folder, especially with a broad instruction like "reorganise these notes".
- Before a bulk shell command, a scripted rename or a large sync push.
- At a point you might want to compare against later, for example the state of a draft when you sent it out.

Naming matters, because the name is what you will scan later. `before auth refactor` beats `backup 3`.

## How a checkpoint differs from an automatic version

| | Automatic version | Checkpoint |
|---|---|---|
| Created by | Every content write | You, deliberately |
| Content stored | What the file looked like before that write | What the file looks like right now |
| Named | No, labelled with the run's summary | Yes, 1 to 60 characters |
| Trimmed away | Yes, only the newest 20 per file survive | Never |
| Covers a folder | No, one file at a time | Yes, the whole subtree in one snapshot |

## Creating one

In the web app, open the file's **History** panel, type a name in the checkpoint field at the top and press **Checkpoint**. The command palette also has **Checkpoint this file**, which names it after the current date and time.

From the terminal, one command covers both a file and a folder:

```bash title="Terminal"
monofile checkpoint /Projects/report.md "before rewrite"
monofile checkpoint /Projects "before auth refactor"
```

From the API, the `checkpoint` tool takes a path and a name, and needs the `files:write` scope:

```http
POST /api/tools/checkpoint
{"path": "/Projects", "name": "before auth refactor"}
```

```bash title="Terminal"
curl -X POST "https://www.monofile.ai/api/tools/checkpoint" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Projects", "name": "before auth refactor"}'
```

A folder checkpoint walks the subtree and snapshots every file in it, subfolders included. The response gives the number of files it captured and an id you can restore later.

## Limits

| Limit | Value | What happens at the edge |
|---|---|---|
| Checkpoints per file | 10 | The call fails with `CAP_EXCEEDED`; restore or move on from an old one first |
| Files per folder checkpoint | 200 | The call fails with `CAP_EXCEEDED`; checkpoint a narrower folder |
| Name length | 1 to 60 characters | Longer names are rejected |

A folder checkpoint covers the text files in the subtree. It skips media files, whose content lives in object storage.

## Restoring one

A file checkpoint shows up in that file's history under the name you gave it. Select it, preview it, and restore it like any other version. Monofile captures your current content first, so you can undo the restore.

A folder checkpoint is one changeset, so you restore the whole subtree at once by reverting it:

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

> [!NOTE]
> Expect a conflict report the first time. Reverting refuses by default when files have changed since the snapshot, and after an afternoon of work they have. Check the list of files it names, then re-run with `--force`. Monofile versions your current content before overwriting anything. [[Reverting Safely]] walks through that in full.

## Next steps

:::cards
- [[Reverting Safely]] — Restore a file or undo a whole run, and what happens on a conflict.
- [[Changesets]] — Runs grouped into one reviewable, revertable unit.
- [[How Versioning Works]] — Automatic version capture on every write, and how long versions last.
:::