# 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

## Usage

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

## Examples

```shell
# 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

- [`atmos artifacts publish`](/cli/commands/artifacts/publish)
- [`atmos artifacts verify`](/cli/commands/artifacts/verify)
- [Artifacts Configuration](/cli/configuration/artifacts)