Skip to main content

atmos artifacts pull

Download an artifact, verify every consumed descriptor, and materialize its content in a local directory. The content is validated in staging first, so an interrupted or failed pull never leaves a half-written output.

Experimental
atmos artifacts pull --help

Usage​

atmos artifacts pull <ref> --repository=<alias> --output=<dir> [flags]

Examples​

# Pull a version into a directory
atmos artifacts pull components/terraform/vpc:1.2.0 --repository=shared --output=./vendor/vpc

# Replace an existing, different output directory
atmos artifacts pull components/terraform/vpc:1.2.0 --repository=shared --output=./vendor/vpc --force

# Pull by digest
atmos artifacts pull 'components/terraform/vpc@sha256:<digest>' --repository=shared --output=./vendor/vpc

Behavior​

Atmos resolves the reference once and reads only that pinned content, so a tag that moves mid-operation is never followed. Each consumed content descriptor is verified against its digest.

When the effective policy requires a signature or supplies trust constraints, verification runs before anything is materialized, and a failure leaves the output untouched. Without trust configuration the artifact is consumed as unchecked and is not reported as verified.

An existing output directory with different content needs --force. The new content is validated in staging and then replaces the directory; stale files are never overlaid. On Windows, atomic replacement of an existing directory is unavailable: the command fails without changing it, even with --force. Choose a new output path. --force does not bypass signature verification.

Arguments​

ref (required)

name:version or name@sha256:<digest>.

Flags​

--repository, -r (required)

Configured repository alias. Environment variable: ATMOS_ARTIFACTS_REPOSITORY

--output (required)

Directory to materialize the artifact into. Environment variable: ATMOS_ARTIFACTS_OUTPUT

--force, -f (optional)

Replace an existing, different output directory where atomic replacement is supported. Environment variable: ATMOS_ARTIFACTS_FORCE

--format (optional)

Output format: text (default), json, or yaml. Environment variable: ATMOS_ARTIFACTS_FORMAT

Output​

Stdout carries outcome, ref, location (the output directory), the digests, and size. Stderr carries the status line.

The outcome is read when the command downloaded the artifact into the output directory. It is unchanged when the output directory already matches the artifact, so nothing is downloaded and a repeated pull succeeds.

Errors​

Missing repository or --output
Exit code 2, with a hint that names the flag and its environment variable.
Malformed reference
A reference without a version or digest fails: there is no implicit latest.
Not found
The hint points to atmos artifacts list.
Existing different output
On supported platforms, pass --force to replace it. On Windows, use a new output path; the existing directory is preserved.
Integrity or verification failure
A digest mismatch, or a required signature that is missing or untrusted, fails before materialization.

Every failure exits with a nonzero status. For failures reached while the command runs, --format=json or --format=yaml still writes the result to stdout with outcome: failed and an error field. Argument and flag parsing failures, such as a missing reference or an unknown flag, are rejected before the command runs and do not produce a structured result.

Related​