Repository Checkpoints

A repository checkpoint is a portable, immutable archive of one repository sequence. It is useful for durable exports and for verifying a snapshot outside a running WarmHub service.

Checkpoint status, latest, access, and download commands require unrestricted repo:read plus repo:checkpoint-read. Generate and retry also require repo:checkpoint-generate; repo:admin remains compatible for those operations but does not substitute for repo:checkpoint-read. Checkpoint commands do not treat a public repository as an anonymous export surface. Newly issued owner/admin role PATs include the narrow checkpoint scopes. Any existing personal access token (PAT) missing repo:checkpoint-read must be reissued to use checkpoint commands.

Generate and inspect

wh repo checkpoint generate acme/widgets --wait
wh repo checkpoint status acme/widgets --checkpoint <checkpoint-id>
wh repo checkpoint latest acme/widgets
wh repo checkpoint retry acme/widgets --checkpoint <checkpoint-id> --wait

Command	Purpose
wh repo checkpoint generate [org/repo] [--at-least-repo-seq n] [--wait]	Request a checkpoint at the current repository sequence, or no earlier than n. --wait polls until it reaches a terminal state.
wh repo checkpoint status [org/repo] (--checkpoint id | --repo-seq n)	Show the lifecycle status for one checkpoint.
wh repo checkpoint latest [org/repo]	Show the latest completed checkpoint, or report that none exists.
wh repo checkpoint retry [org/repo] --checkpoint id [--wait]	Retry a failed checkpoint.

status requires exactly one selector. A checkpoint that does not exist returns NOT_FOUND; that result does not reveal data to callers without checkpoint authority.

Get a short-lived artifact URL

Use access when another process should fetch an artifact directly:

wh repo checkpoint access acme/widgets --latest --archive

wh repo checkpoint access acme/widgets \
  --checkpoint <checkpoint-id> --manifest --json

Like download, access requires exactly one checkpoint selector (--latest, --checkpoint, or --repo-seq) and one artifact selector (--archive, --manifest, or --chunk). Pretty output includes the signed URL, expiration, checkpoint identity, byte length, SHA-256, and content type. Use --json for structured output.

The URL is a short-lived bearer credential. Avoid logs and shell history that may retain command output, and do not share the URL.

Download an artifact

Choose exactly one checkpoint selector and one artifact selector:

wh repo checkpoint download acme/widgets \
  --latest --archive --output checkpoint.zip

wh repo checkpoint download acme/widgets \
  --checkpoint <checkpoint-id> --manifest --output repository-checkpoint.json

wh repo checkpoint download acme/widgets \
  --repo-seq 42 --chunk records/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef/part-000000.jsonl --output chunk.ndjson

Selector	Meaning
--latest	The latest completed checkpoint.
--checkpoint id	A specific checkpoint identifier.
--repo-seq n	The checkpoint at one repository sequence.

Artifact	Meaning
--archive	The complete checkpoint archive.
--manifest	The checkpoint manifest.
--chunk path	One manifest-declared checkpoint chunk.

--output PATH creates a new file and refuses to overwrite an existing path. Use --output - only with the default --format pretty to stream raw bytes to stdout. The CLI verifies the downloaded byte count and SHA-256 before publishing a file.

The control-plane request returns a short-lived signed URL. The subsequent object download is a raw signed GET; it intentionally has no WarmHub Authorization header. Treat that URL as a credential and avoid logging or sharing it.

Verify offline

wh repo checkpoint verify checkpoint.zip

verify reads only the archive on disk. It does not resolve a CLI profile, call WarmHub, or fetch any network resource, so it works in disconnected environments.

For programmatic lifecycle control, see the repository checkpoint SDK reference.