Operation: List Checkpoints
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Operation: List Checkpoints is a core management function of the chkpt system designed to retrieve and display historical workspace snapshots. It allows users and automated tools to browse available recovery points, inspect their associated metadata (such as timestamps, file counts, and messages), and identify specific IDs for subsequent operations like Restore or Delete.
The operation acts as the primary interface for exploring the content-addressed storage catalog. It supports filtering via limits and provides different levels of detail (e.g., short IDs vs. full UUIDs) depending on the interface used (CLI, NAPI, or MCP).
Sources: README.md:58-60, crates/chkpt-cli/src/main.rs:136-168, crates/chkpt-plugin/skills/chkpt/references/cli-commands.md:30-45
Architecture and Data Flow
Listing checkpoints involves a multi-layered approach starting from the user interface and descending into the core library's interaction with the persistent metadata catalog.
Metadata Retrieval Flow
When a list request is initiated, the system identifies the project's unique storage directory and queries the catalog.sqlite database. The catalog maintains the definitive record of all snapshots saved for a specific workspace.
The flow ensures that metadata is retrieved efficiently from the SQLite-backed catalog without needing to scan the heavy blob or tree storage directories.
Sources: crates/chkpt-core/src/ops/list.rs, crates/chkpt-plugin/skills/chkpt/references/store-layout.md:7-14, crates/chkpt-cli/src/main.rs:136-138
Data Structures and Catalog Schema
The list operation relies on the snapshots table within the catalog.sqlite file located in the project's store directory.
Snapshot Metadata Fields
The following table describes the fields typically retrieved during a list operation:
| Field | Type | Description |
|---|---|---|
id | UUID/String | Unique identifier for the checkpoint. |
created_at | Timestamp | Date and time the snapshot was created. |
message | String (Optional) | User-provided description of the checkpoint. |
total_files | Integer | Count of files captured in the workspace at save time. |
total_bytes | Integer | Total size of the workspace at save time. |
new_objects | Integer | Number of unique blobs added to the store in this snapshot. |
Sources: crates/chkpt-plugin/skills/chkpt/references/store-layout.md:33-44, crates/chkpt-cli/src/main.rs:154-165
Interface Implementations
CLI Interface
The CLI provides a formatted table output. It supports two main flags:
-n, --limit <N>: Restricts the output to the most recent N checkpoints.--full: Displays the complete UUID instead of the truncated 8-character ID.
# Example CLI Usage
chkpt list --limit 5 --full
Sources: crates/chkpt-cli/src/main.rs:136-168, crates/chkpt-cli/skills/chkpt/references/cli-commands.md:30-45
NAPI (Node.js) Interface
The Node.js bindings expose an asynchronous list function that returns an array of snapshot objects. Tests indicate that the output is ordered newest first.
// Example NAPI Usage
import { list } from "chkpt";
const snapshots = await list(workspacePath, 10);
console.log(snapshots[0].message);
Sources: crates/chkpt-napi/test/ops.spec.ts:31-43
MCP / Plugin Interface
In the Claude Code plugin, the checkpoint_list tool is used not just for display but as a prerequisite for identifying real snapshot IDs before performing inspection or restoration tasks.
Sources: crates/chkpt-plugin/skills/chkpt/SKILL.md:46-51, crates/chkpt-plugin/README.md:16
Operational Logic: Interactive Selection
A unique aspect of the list operation within the CLI's restore command is the interactive selection logic. If a user runs chkpt restore without an ID, the system internally executes a list operation and presents a selectable menu using dialoguer.
Sources: crates/chkpt-cli/src/main.rs:172-209
Conclusion
Operation: List Checkpoints provides the visibility necessary to manage the chkpt storage system. By querying the SQLite catalog, it offers a lightweight way to audit workspace history across various interfaces. Whether used for manual inspection via the CLI or as a programmatic step in an automation workflow, it ensures that users can accurately target specific states for restoration or cleanup.