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.
Inspect
Section titled “Inspect”wh graph checkpoint status acme/widgets --checkpoint <checkpoint-id>wh graph checkpoint latest acme/widgets| Command | Purpose |
|---|---|
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.
Get a short-lived artifact URL
Section titled “Get a short-lived artifact URL”Use access when another process should fetch an artifact directly:
wh graph checkpoint access acme/widgets --latest --archive
wh graph checkpoint access acme/widgets \ --checkpoint <checkpoint-id> --manifest --jsonLike 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.
Download an artifact
Section titled “Download an artifact”Choose exactly one checkpoint selector and one artifact selector:
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| Selector | Meaning |
|---|---|
--latest | The latest completed checkpoint. |
--checkpoint id | A specific checkpoint identifier. |
--graph-seq n | The checkpoint at one graph 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
Section titled “Verify offline”wh graph checkpoint verify checkpoint.zipverify 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.