stax pull

Pull an artifact from an OCI registry into the project-local cache. Once cached, the artifact can be inspected, materialized, or extracted without additional network requests.

Usage

stax pull ghcr.io/myorg/agents/backend-engineer:3.1.0
stax pull ghcr.io/myorg/agents/backend-engineer@sha256:a3f8c1…e7d2

Resolving references

Pull accepts two forms of reference:

• Tag (backend-engineer:3.1.0) — Resolves to the current digest for that tag. Tags are mutable — the same tag may point to different digests over time.
• Digest (backend-engineer@sha256:abc...) — Resolves to an exact, immutable artifact. Use digests when reproducibility matters (CI, production deployments).

Caching behavior

Pulled artifacts are stored in the project-local cache at .stax/cache/:

• If an artifact with the same digest already exists locally, the pull is a no-op
• Layers shared between artifacts are deduplicated — pulling a new version only downloads changed layers
• Source artifacts referenced by agents are cached in the same store and reused across multiple materializations

Authentication

Private registries require authentication. See stax login.

Example output

Pulled ghcr.io/myorg/agents/backend-engineer:3.1.0
  layers: 6
  cached: /repo/.stax/cache

Related commands

• stax materialize — Translate the pulled artifact into runtime files
• stax inspect — View artifact metadata
• stax push — Push an artifact to a registry