Skip to main content
Archive download is useful for CI pipelines, offline processing, and environments where adapters are not available.

​
Fast path: download.sh

curl -s https://api.shelv.dev/v1/helpers/download.sh | SHELV_KEY=sk_... SHELF_PUBLIC_ID=shf_a1b2c3d4e5f60718293a4b5c sh
Or download and run locally: 
curl -sO https://api.shelv.dev/v1/helpers/download.sh
sh download.sh --key sk_... --shelf-public-id shf_a1b2c3d4e5f60718293a4b5c --target ./my-shelf
Script options:
FlagEnv varDefault
--keySHELV_KEYrequired
--shelf-public-idSHELF_PUBLIC_IDrequired
--targetTARGET./shelf
--apiSHELV_API_URLhttps://api.shelv.dev

​
Manual API flow

Request a presigned URL: 
curl "https://api.shelv.dev/v1/shelves/{shelfPublicId}/archive-url?ttl=600" \
  -H "Authorization: Bearer sk_your_api_key"
Rules:
  • Shelf must be ready or review
  • ttl range is 60 to 3600 seconds
  • Default ttl is 300
The first request may start archive preparation, so use short polling loops in automation. If archive is not ready yet, you get 202: 
{
  "status": "generating",
  "retryAfter": 5
}
Poll after retryAfter seconds until 200, then download from returned url. On 401, refresh credentials. On 409, wait for an eligible shelf status (ready or review) before retrying.

​
Verify integrity

Use sha256 from the 200 response: 
echo "$EXPECTED_SHA  archive.tar.gz" | sha256sum --check
download.sh performs verification automatically when a SHA-256 tool is available.

​
Choosing retrieval mode

  • Archive: CI/offline snapshots
  • Sandbox adapters: provider-native runtime hydration
  • JSON tree: in-memory workflows
  • Single file: targeted reads
For reproducible jobs, log the returned version timestamp with your build metadata.