> ## 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, and search 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 |
| `--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`](/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 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`](/cli-reference/search). See that page for the [flags](/cli-reference/search#flags), inline filters, code search, and the interactive result view.