> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkpoints

> Shadow git checkpointing for file-level undo/restore

The `checkpoint` command manages file-level checkpoints using shadow git — save, list, diff, restore, and rewind workspace snapshots.

<Note>
  All `checkpoint` subcommands respect `checkpoints.storage_dir` from your project config (`agents.yaml`). This means `praisonai checkpoint list`, `restore`, and `diff` operate on the same store as `praisonai code --checkpoints` sessions and `praisonai run` auto-checkpoints.

  ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # agents.yaml
  checkpoints:
    storage_dir: ./.praisonai/checkpoints   # optional
  ```
</Note>

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Save a checkpoint
praisonai checkpoint save "Before refactoring"

# One-liner undo after a bad run
praisonai run --restore last
```

## Usage

### Save Checkpoint

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai checkpoint save "Checkpoint message"
praisonai checkpoint save "Checkpoint message" --allow-empty
praisonai checkpoint save "Checkpoint message" -w /path/to/project
```

| Flag            | Short | Description                                        | Default           |
| --------------- | ----- | -------------------------------------------------- | ----------------- |
| `--allow-empty` |       | Allow a checkpoint even when no files have changed | `false`           |
| `--workspace`   | `-w`  | Workspace directory to snapshot                    | current directory |

**Expected Output:**

```
✅ Checkpoint saved: abc12345
   Message: Before refactoring
   Files changed: 3
```

### List Checkpoints

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai checkpoint list
praisonai checkpoint list --limit 10
praisonai checkpoint list -n 5 -w /path/to/project
```

| Flag          | Short | Description                           | Default           |
| ------------- | ----- | ------------------------------------- | ----------------- |
| `--limit`     | `-n`  | Maximum number of checkpoints to show | `20`              |
| `--workspace` | `-w`  | Workspace directory                   | current directory |

**Expected Output:**

```
╭─ Checkpoints ────────────────────────────────────────────────────────────────╮
│  1. [abc12345] Before refactoring (2024-12-24 07:30:00)                     │
│  2. [def67890] Initial state (2024-12-24 07:25:00)                          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

### Show Diff

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai checkpoint diff
praisonai checkpoint diff last
praisonai checkpoint diff abc12345
praisonai checkpoint diff abc12345 def67890
praisonai checkpoint diff last def67890
praisonai checkpoint diff -w /path/to/project
```

| Flag          | Short | Description         | Default           |
| ------------- | ----- | ------------------- | ----------------- |
| `--workspace` | `-w`  | Workspace directory | current directory |

Both the `from` and `to` arguments accept a full id, short id, unique prefix, or the alias `last` / `latest`.

### Restore Checkpoint

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai checkpoint restore last
praisonai checkpoint restore abc12345
praisonai checkpoint restore --step 3
praisonai checkpoint restore abc1 -w /path/to/project
```

| Flag          | Short | Description                                                 | Default           |
| ------------- | ----- | ----------------------------------------------------------- | ----------------- |
| `--step`      |       | Restore the per-step checkpoint tagged with this step index |                   |
| `--workspace` | `-w`  | Workspace directory                                         | current directory |

A checkpoint id and `--step` are mutually exclusive — providing both returns `Provide either a checkpoint id/'last' or --step N, not both`.

### Rewind Checkpoints

Rewind the workspace back N checkpoints from the latest. `rewind` is the shortest command for undoing the most recent checkpointed change — you don't need to remember an id.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai checkpoint rewind            # undo the last checkpoint (steps=1)
praisonai checkpoint rewind 3          # step back 3 checkpoints from the latest
praisonai checkpoint rewind 2 -w /path/to/project
```

| Argument / Flag      | Short | Description                                        | Default           |
| -------------------- | ----- | -------------------------------------------------- | ----------------- |
| `steps` (positional) |       | How many checkpoints to step back (must be `>= 1`) | `1`               |
| `--workspace`        | `-w`  | Workspace directory                                | current directory |

**Expected Output:**

```
✅ Rewound 1 checkpoint(s) to: abc12345
```

**When to use `rewind` vs `restore`:**

* `restore <id>` — you know the exact checkpoint id and want to jump there.
* `rewind [steps]` — you just want to undo the last N checkpoints without looking up ids (equivalent to `restore` on `list_checkpoints()[steps]`).

<Note>
  `steps` must be `>= 1`. Passing `0` or a negative value is rejected by the CLI before the service runs.
</Note>

<Note>
  `rewind` can reach shadow-git commits older than `max_checkpoints`. The `max_checkpoints` limit only trims the in-memory listing — the underlying shadow git retains every commit, so `rewind N` still works even if `N > max_checkpoints`.
</Note>

**Errors:**

```
$ praisonai checkpoint rewind 99
✗ Failed to rewind: Cannot rewind 99 step(s): only 3 checkpoint(s) available
```

* `Cannot rewind 5 step(s): only 2 checkpoint(s) available` — history too short.
* `steps must be >= 1` — invalid input.

### Delete Checkpoints

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai checkpoint delete
praisonai checkpoint delete --yes
praisonai checkpoint delete -y -w /path/to/project
```

| Flag          | Short | Description                              | Default           |
| ------------- | ----- | ---------------------------------------- | ----------------- |
| `--yes`       | `-y`  | Skip the interactive confirmation prompt | `false`           |
| `--workspace` | `-w`  | Workspace directory                      | current directory |

Omitting `--yes` prompts: `Delete all checkpoints? [y/N]`.

***

## Reference Aliases

Every subcommand that accepts a checkpoint reference (`restore`, `diff`, `run --restore`) supports these forms:

| Reference                          | Resolves to                                               |
| ---------------------------------- | --------------------------------------------------------- |
| `last` or `latest`                 | The newest checkpoint (list is newest-first)              |
| Full id (e.g. `abc12345def67890…`) | Exact match                                               |
| Short id (e.g. `abc12345`)         | Exact short-id match                                      |
| Unique prefix (e.g. `abc1`)        | Matches if exactly one checkpoint starts with that prefix |

**Ambiguous prefix example:**

```
$ praisonai checkpoint restore abc
Error: Ambiguous checkpoint reference: abc
```

Ambiguous prefixes are rejected so a workspace-mutating restore never targets the wrong checkpoint.

***

## Python API

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import asyncio
from praisonaiagents.checkpoints import CheckpointService

async def main():
    service = CheckpointService(workspace_dir="/path/to/project")
    await service.initialize()
    
    # Save checkpoint (optionally tag with a step index)
    result = await service.save("Before changes")
    await service.save("After step 0", step=0)
    print(f"Saved: {result.checkpoint.short_id}")
    
    # List checkpoints
    checkpoints = await service.list_checkpoints()
    for cp in checkpoints:
        print(f"{cp.short_id}: {cp.message} (step={cp.step})")
    
    # Restore by id or step index
    await service.restore(result.checkpoint.id)
    await service.restore(step=0)
    
    # Rewind N checkpoints back from the latest (default 1)
    result = await service.rewind(1)
    print(f"Rewound to: {result.checkpoint.short_id}")
    await service.rewind(3)

asyncio.run(main())
```

***

## See Also

* [Shadow Git Checkpointing Feature](/docs/features/checkpoints)
* [Run command — Checkpoint & Rewind](/docs/cli/run) — `--restore` and `--no-checkpoint` flags