Skip to content

Graph Checkpoints

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

Checkpoint commands require unrestricted repo:read plus repo:checkpoint-read. Checkpoint commands do not treat a public graph as an anonymous export surface. (Graphs were formerly called repos, which is why the scope names still say repo.) 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.

Terminal window
wh graph checkpoint status acme/widgets --checkpoint <checkpoint-id>
wh graph checkpoint latest acme/widgets
CommandPurpose
wh graph checkpoint status [org/graph] (--checkpoint id | --graph-seq n)Show the lifecycle status for one checkpoint.
wh graph checkpoint latest [org/graph]Show the latest completed checkpoint, or report that none exists.

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.

Use access when another process should fetch an artifact directly:

Terminal window
wh graph checkpoint access acme/widgets --latest --archive
wh graph checkpoint access acme/widgets \
--checkpoint <checkpoint-id> --manifest --json

Like download, access requires exactly one checkpoint selector (--latest, --checkpoint, or --graph-seq) and one artifact selector (--archive, --manifest, or --chunk). Pretty output includes the signed URL, expiration, checkpoint identity, graph sequence, 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.

Choose exactly one checkpoint selector and one artifact selector:

Terminal window
wh graph checkpoint download acme/widgets \
--latest --archive --output checkpoint.zip
wh graph checkpoint download acme/widgets \
--checkpoint <checkpoint-id> --manifest --output graph-checkpoint.json
wh graph checkpoint download acme/widgets \
--graph-seq 42 --chunk records/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef/part-000000.jsonl --output chunk.ndjson
SelectorMeaning
--latestThe latest completed checkpoint.
--checkpoint idA specific checkpoint identifier.
--graph-seq nThe checkpoint at one graph sequence.
ArtifactMeaning
--archiveThe complete checkpoint archive.
--manifestThe checkpoint manifest.
--chunk pathOne 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.

Terminal window
wh graph 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 graph checkpoint SDK reference.