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

# checkpoint

> List, explain, measure, search, and delete checkpoints.

Work with checkpoints captured by Entire.

```bash theme={null}
entire checkpoint SUBCOMMAND
```

`entire checkpoint` is also available as `entire cp` and `entire checkpoints`.

## checkpoint list

List checkpoints on the current branch.

```bash theme={null}
entire checkpoint list [flags]
```

| Flag | Description |
| - | - |
| `--json` | Output as JSON instead of the human view |
| `--no-pager` | Disable pager output |
| `--outgoing` | List the checkpoints your next `git push` sends, read locally with no network call. `git-refs` backend only |
| `--pending` | List the live session's shadow-branch rewind points, plus logs-only resume points recovered from commits whose logs are already condensed, instead of condensed checkpoints |
| `--session ID` | Filter checkpoints by session ID (or prefix). Not valid with `--pending` |

## checkpoint explain

Show human-readable context for checkpoints, sessions, and commits. Add `--generate` for an AI-written summary.

```bash theme={null}
entire checkpoint explain [CHECKPOINT_ID | COMMIT_SHA] [flags]
```

| Flag | Description |
| - | - |
| `-c, --checkpoint ID` | Explain a specific checkpoint (ID or prefix) |
| `--commit SHA` | Explain a specific commit (SHA or ref, "commit-ish") |
| `--force` | Regenerate summary even if one already exists (requires `--generate`) |
| `--full` | Show full parsed transcript (all prompts/responses) |
| `--generate` | Generate an AI summary for the checkpoint |
| `--insecure-http-auth` | Allow plain HTTP auth for `--repo`. Local development only. |
| `--json` | Output metadata as JSON. See [Machine-Readable Output](#machine-readable-output). |
| `--limit N` | Cap the list view at N checkpoints. Defaults to `100`. Only meaningful with `--json`. |
| `--no-pager` | Disable pager output |
| `--raw-transcript` | Show raw transcript file (JSONL format) |
| `--repo REPO` | A forge-qualified reference: `gh/OWNER/REPO` or `et/PROJECT/REPO`. See [Explain a Checkpoint in Another Repository](#explain-a-checkpoint-in-another-repository). |
| `--search-all` | Search all commits (no branch/depth limit, may be slow) |
| `--session ID` | Filter checkpoints by session ID (or prefix) |
| `--session-index N` | Pick a session within a multi-session checkpoint, 0-based. Defaults to the latest. Only meaningful with `--transcript` or `--raw-transcript`. |
| `-s, --short` | Show summary only (omit prompts and files) |
| `--task ID` | With `--transcript`, stream a subagent's stored transcript instead, selected by `tool_use_id` or `agent_id` as listed under `tasks` in `--json`. |
| `--summary-timeout-seconds N` | Hard deadline in seconds for `--generate`. Overrides the `summary_timeout_seconds` setting. `0` uses the setting; if that is also unset, no automatic deadline applies. |
| `--transcript` | Stream stored checkpoint transcript bytes (JSONL) to stdout: a session's, or a subagent's with `--task` |

> [!NOTE]
>
> The `--generate` flag requires the configured provider CLI, such as Claude CLI, to be installed and authenticated.

### Machine-Readable Output

`--json` emits metadata only. With no target it lists checkpoints; with a target it emits a single checkpoint envelope, including its subagent task records under `tasks` and the full session token breakdown (`subagent_tokens`, `subagent_tokens_complete`, `api_call_count`). Transcript bytes are never embedded in that envelope.

To get the transcript itself, use `--transcript`, which streams the stored checkpoint transcript bytes to standard output:

```bash theme={null}
entire checkpoint explain 01KVBJCW --json
entire checkpoint explain 01KVBJCW --transcript > session.jsonl
entire checkpoint explain 01KVBJCW --transcript --session-index 0 > first-session.jsonl
entire checkpoint explain 01KVBJCW --transcript --task TOOL_USE_ID > subagent.jsonl
```

### Explain a Checkpoint in Another Repository

`--repo` reads a checkpoint owned by a different repository through that repository's Entire API. It takes a forge-qualified reference — `gh/OWNER/REPO` or `et/PROJECT/REPO`, or a full `entire://` URL — and refuses a bare `owner/repo`. This is the drill-down for a cross-repo [`entire search`](https://docs.entire.com/cli-reference/search) hit. Nothing is written to the current repository.

```bash theme={null}
entire checkpoint explain CHECKPOINT_ID --repo gh/owner/name
```

This needs the full checkpoint ID, passed positionally or with `--checkpoint`, and a checkpoint that has been pushed.

## checkpoint tokens

Show token usage and optimization recommendations for a checkpoint.

```bash theme={null}
entire checkpoint tokens CHECKPOINT_ID [flags]
```

| Flag | Description |
| - | - |
| `--agent-brief` | Output compact next-step guidance for agents |
| `--compare ID` | Compare against a baseline checkpoint ID |
| `--json` | Output as JSON |

`--json` and `--agent-brief` are mutually exclusive.

The report resolves its target through the same path as `checkpoint explain`: an unambiguous checkpoint ID prefix, or a commit-ish carrying an `Entire-Checkpoint` trailer. Metadata missing locally is fetched from the checkpoint remote.

```bash theme={null}
entire checkpoint tokens 01KVBJCW
entire checkpoint tokens 01KVBJCW --compare 01KVBK7Q
entire checkpoint tokens 01KVBJCW --json
```

## checkpoint delete

Delete one checkpoint from this repository and from every checkpoint remote that holds it.

```bash theme={null}
entire checkpoint delete CHECKPOINT_ID [flags]
```

The full checkpoint ID is required; prefixes are not accepted. Deleting from a remote cannot be undone. Without `--force`, the command asks for confirmation and refuses when it cannot prompt.

| Flag | Description |
| - | - |
| `--dry-run` | Print what would be deleted without changing anything |
| `-f`, `--force` | Delete without asking for confirmation |
| `--json` | Output as JSON |
| `--local-only` | Delete only the local copy; leave every remote untouched |
| `--remote REMOTE` | Limit remote deletion to this remote; the local copy is still deleted. Repeatable. `checkpoint_remote` names the dedicated checkpoint remote |

> [!WARNING]
>
> Deleting a checkpoint is not a full purge. Other checkpoints from the same session are listed but not deleted, and each one carries the session's full transcript, so the session stays visible on entire.com while any of them remain. On the legacy `entire/checkpoints/v1` branch, the checkpoint is removed from the branch tip only, and the branch's history still contains it.

On the `git-branch` backend, a local removal reaches the sync remote on the next `git push`, so `--local-only` (or a `--remote` selection that leaves that remote out) is refused while it holds a copy or cannot be reached. With `push_sessions` disabled the removal is not pushed, but re-enabling it later pushes it.

```bash theme={null}
entire checkpoint delete 01KVBJCWQ1A2B3C4D5E6F7G8H9 --dry-run
entire checkpoint delete 01KVBJCWQ1A2B3C4D5E6F7G8H9
entire checkpoint delete 01KVBJCWQ1A2B3C4D5E6F7G8H9 --remote origin --force
```

## checkpoint search

Search checkpoints using semantic and keyword matching.

```bash theme={null}
entire checkpoint search [QUERY] [flags]
```

`entire checkpoint search` is an alias for [`entire search`](https://docs.entire.com/cli-reference/search). See that page for the [flags](https://docs.entire.com/cli-reference/search.md#flags), inline filters, code search, and the interactive result view.
