CLI Command Reference
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The chkpt CLI is a fast, content-addressable checkpoint system designed to save and restore entire workspace snapshots without interfering with Git. It utilizes XXH3-128 hashing for deduplication and LZ4 compression, providing a local "save game" mechanism for developers to protect their work before risky operations like refactors or dependency updates.
The CLI serves as the primary manual interface for the chkpt engine, wrapping core operations provided by the chkpt-core library. It supports four primary actions: saving snapshots, listing historical checkpoints, restoring files to a specific state, and deleting old checkpoints.
Sources: CLAUDE.md:5-9, README.md:3-8, crates/chkpt-cli/src/main.rs:11-16
Command Architecture and Workflow
The CLI is built using the clap crate for argument parsing and dialoguer for interactive selections. It operates by identifying the current working directory as the workspace and interacting with a local store usually located in ~/.chkpt/stores/.
General Execution Flow
The following diagram illustrates how the CLI processes a user command from invocation to execution via the core library.
The CLI implements visual feedback using indicatif progress bars for long-running operations like scanning and processing files.
Sources: crates/chkpt-cli/src/main.rs:11-48, crates/chkpt-cli/src/main.rs:118-124, crates/chkpt-cli/src/main.rs:136-137
Core Commands
chkpt save
Saves a snapshot of the current workspace. It scans the filesystem according to .chkptignore rules and records new objects in the store.
| Option | Flag | Description |
|---|---|---|
| Message | -m, --message | An optional label describing the checkpoint state. |
| Include Deps | --include-deps | Includes directories like node_modules or .venv usually ignored by default. |
Usage Example:
chkpt save -m "before: refactoring auth module" --include-deps
Sources: crates/chkpt-cli/src/main.rs:19-27, crates/chkpt-cli/skills/chkpt/references/cli-commands.md:5-24
chkpt list
Displays a table of available checkpoints sorted newest first. By default, it shows truncated IDs and metadata.
| Option | Flag | Description |
|---|---|---|
| Limit | -n, --limit | Maximum number of checkpoints to display. |
| Full | --full | Displays the complete UUID instead of the short 8-character prefix. |
Execution Logic:
chkpt restore
Restores the workspace to a previous state. If no ID is provided, the CLI enters an interactive selection mode.
Safety Requirement: It is strongly recommended to use the --dry-run flag first to preview changes.
chkpt restore [id|latest] [--dry-run]
| Argument | Description |
|---|---|
id | The snapshot ID, a prefix, or the keyword latest. |
--dry-run | Previews files to be added, changed, or removed without modifying the disk. |
Sources: crates/chkpt-cli/src/main.rs:36-43, crates/chkpt-cli/src/main.rs:189-215
chkpt delete
Removes a specific checkpoint from the catalog.
chkpt delete <id>
Sources: crates/chkpt-cli/src/main.rs:44-47, crates/chkpt-cli/src/main.rs:238-241
Automation and Usage Patterns
The CLI is designed to be integrated into automation workflows (such as Claude Code or MCP servers). Certain patterns are recommended for optimal safety.
Recommended Save Scenarios
- Before Risky Operations: Large-scale refactors (changing >5 files), bulk deletions, or dependency changes.
- After Milestones: Major feature completion or when all tests are passing.
Sources: crates/chkpt-cli/skills/chkpt/references/automation-patterns.md:3-23
Error Handling
The CLI translates core errors into actionable feedback for the user.
| Error Message | Meaning | Action |
|---|---|---|
Lock held by another process | Concurrent chkpt operation detected. | Wait for the other process to finish. |
Snapshot not found | Invalid ID or prefix provided. | Run chkpt list to verify IDs. |
Store corrupted | Integrity issues in the SQLite catalog or blobs. | Inspect the ~/.chkpt/stores/ directory. |
Sources: crates/chkpt-cli/skills/chkpt/references/cli-commands.md:95-102, crates/chkpt-core/src/config.rs:22-26
Conclusion
The chkpt CLI provides a robust and user-friendly interface for managing local workspace snapshots. By leveraging content-addressed storage and incremental updates, it ensures that even large projects (like the Linux kernel or React) can be snapshotted and restored in fractions of a second, providing a critical safety net for developers during complex operations.