Manual Cache Access

Annotated scripts are the usual way to cache automation because Once owns the lookup, execution, and output restoration. Use once cache when an existing tool must perform those steps itself or when you need to inspect the cache.

Once exposes two related stores:

• The blob cache stores bytes under their content digest.
• The action cache maps a digest of declared inputs to an exit code, captured streams, and optional output blobs.

An action result can therefore point to blobs without duplicating their bytes.

Store And Retrieve A Blob

Put a file or standard input into the blob cache. The command prints its BLAKE3 content digest:

digest=$(printf 'hello from Once\n' | once cache blob put)
printf '%s\n' "$digest"

Use that digest to check for the blob and retrieve it:

once cache blob exists "$digest"
once cache blob get "$digest"

exists exits with status zero when the blob is present and status one when it is absent. In JavaScript Object Notation (JSON) or Token-Oriented Object Notation output, it always exits with status zero and reports whether the blob is present.

Record An Action Result

The action cache derives its key from ordered input declarations. This Bash script runs tests with the npm package manager and uses the same inputs for the lookup and the write:

#!/usr/bin/env bash
set -eu

inputs=(
  --input src
  --input test
  --input package-lock.json
)

if once cache action get "${inputs[@]}" --if-success; then
  printf 'tests already passed for these inputs\n'
  exit 0
fi

npm test
once cache action put "${inputs[@]}"

put records exit code zero by default. The next lookup succeeds only when the same ordered inputs produce a cache hit whose recorded exit code is zero.

Use an output mapping when the result includes an artifact:

artifact_inputs=(--input src --input package-lock.json)
artifact_digest=$(once cache blob put build/archive.tar)
once cache action put "${artifact_inputs[@]}" \
  --output build/archive.tar="$artifact_digest"

Read the action result with --format json to obtain the output digest, then pass that digest to once cache blob get when restoring the artifact.

Input Declarations

Declaration	Meaning
<path>	A file or directory. Directory entries are sorted before hashing.
path:<path>	An explicit path form for names that contain :.
value:<text>	A literal value.
env:<NAME>	An environment variable name and value. An unset variable contributes an empty value.
-	Standard input. It may appear once across all inputs.

Input order is significant. Declaring a followed by b produces a different key from declaring b followed by a.

Command Summary

Command	Purpose
once cache blob put [<path>]	Stores bytes from a file or standard input and prints the digest.
once cache blob get <digest>	Retrieves bytes by digest.
once cache blob exists <digest>	Checks whether a digest is present.
once cache action get --input <declaration> ...	Looks up a result derived from ordered inputs.
once cache action get ... --if-success	Succeeds only for a hit whose recorded exit code is zero.
once cache action put --input <declaration> ...	Records an action result and optional stream or output digests.
once cache action forget <digest>	Removes an action result by its precomputed digest.
once cache stats	Reports entry counts and local disk usage.

Blob reads and action lookups use the remote provider configured for the workspace when the requested data is not available locally.

Next

Continue to Infrastructure to keep the local workflow while sharing cache records with other machines. Use the cache command reference for every flag and output format.