# atmos artifacts

Publish files and directories as named, versioned artifacts, then pull, copy, inspect, list, search, sign, and verify them from one command space. Repositories live in local directories, local archives, S3 buckets, and OCI registries or layouts, and each one is addressed by an alias that you define in `atmos.yaml`.

> ⚠️ Experimental

**Configure Artifact Repositories**

Define repositories, authentication identities, packaging, write coordination, and signature verification policy under the top-level `artifacts` section of `atmos.yaml`.

Configuration Reference[Read more](/cli/configuration/artifacts)

## Usage

```shell
atmos artifacts <subcommand> [flags]
```

## Quick Start

Define `artifact-writer` under [`auth.identities`](/cli/configuration/auth) first, then define two repositories, publish a directory to one, and copy it to the other:

```yaml
artifacts:
  repositories:
    backups:
      kind: local/dir
      options:
        path: ./.artifacts/backups
    shared:
      kind: aws/s3
      identity: artifact-writer
      options:
        bucket: acme-artifacts
        prefix: shared
```

```shell
atmos artifacts publish ./dist --repository=backups --name=builds/app --version=build-123
atmos artifacts list --repository=backups
atmos artifacts copy builds/app:build-123 --from=backups --to=shared
atmos artifacts pull builds/app:build-123 --repository=shared --output=./restore
```

## Repositories and References

A repository is a collection root that holds many named artifacts. The keys under `artifacts.repositories` (`backups`, `shared`) are arbitrary aliases that you choose, and every command selects a repository by alias with `--repository`. A command that needs a repository fails when you omit it, even when only one is configured. Only `list` and `search` default to all configured repositories.

An artifact reference takes one of two forms:

- **`name:version`** — A name and an explicit version label, for example `components/terraform/vpc:1.2.0`. Names are lowercase, slash-separated paths. Versions follow the OCI tag grammar and are opaque labels; they do not need to be SemVer. A reference without a version is rejected, because there is no implicit `latest`.
- **`name@sha256:<digest>`** — An immutable digest reference. `sign` accepts only this form. Other commands accept it wherever they accept `name:version`.

## Artifact Kinds

The kind says what the content means: `files` for any tree, `scaffold` for a validated scaffold template, and `component/terraform` for a Terraform root module that leaves out working directories, state, and saved plans. [`atmos scaffold publish`](/cli/commands/scaffold/publish) supplies the scaffold kind for you. See [Artifact Kinds](/cli/commands/artifacts/kinds) for what each kind validates, excludes, and records.

## Digests

Results label each digest by what it identifies:

- **`resolved_digest`** — The digest the repository resolved the reference to. On OCI repositories it is the manifest or index digest. On local and S3 repositories it is the Record digest.
- **`record_digest`** — The digest of the portable Record, which binds the name, version, metadata, inventory, content digest, and document digests. For Atmos packages, signatures cover the Record, so evidence survives changes of physical representation. Foreign OCI graphs are signed at their original OCI root.
- **`content_digest`** — The portable digest of the package content (the file inventory and documents), independent of how a repository stores it.
- **`representation_digest`** — The checksum of the stored or transferred representation, such as an archive. It changes when packaging changes, while `content_digest` does not.

A checksum is never a signature. Use [`atmos artifacts verify`](/cli/commands/artifacts/verify) to check signature evidence against your trust policy.

## Output

Every command except `show` prints a result to stdout and reports progress and status messages on stderr, so output pipes cleanly. The `--format` flag selects the rendering:

- `text` (default for single-artifact commands): aligned `name: value` lines. Optional values that do not apply are omitted.
- `json` and `yaml`: a structured result with the same field names, whichever format you choose.
- `table`, `csv`, and `tsv` (additional formats for `list` and `search`).

Single-artifact commands share these named result fields:

- **`outcome`** — `created`, `unchanged`, `replaced`, `deleted`, `read`, `dry-run`, or `failed`.
- **`ref`** — The resolved `name:version` reference.
- **`location`** — The primary storage location: a path, object key, or registry reference.
- **`resolved_digest`, `record_digest`, `content_digest`, `representation_digest`** — The digests described above.
- **`size`** — The payload size in bytes.
- **`lock_scope`** — The actual write-coordination scope of a mutation: `host` or `repository`.

The structured result also carries `operation_id`, `action`, `repository`, `requested_ref`, `duration_ns`, and `diagnostics`, plus command-specific fields. `list` and `search` return an `artifacts` array in which each entry carries `repository`, `ref`, `name`, `version`, `kind`, `labels`, and the digests.

### Failures

A failed command exits with a nonzero status. For a command that runs, `--format=json` or `--format=yaml` writes a result to stdout with `outcome: failed` and an `error` field. Usage errors, such as invalid argument counts or unknown flags, stop execution without a structured result. In text mode, a failure writes nothing to stdout and the error appears on stderr with hints.

## Environment Variables

Every flag has an `ATMOS_ARTIFACTS_` environment variable: `ATMOS_ARTIFACTS_REPOSITORY`, `ATMOS_ARTIFACTS_NAME`, `ATMOS_ARTIFACTS_VERSION`, `ATMOS_ARTIFACTS_KIND`, `ATMOS_ARTIFACTS_FORCE`, `ATMOS_ARTIFACTS_DRY_RUN`, `ATMOS_ARTIFACTS_LABELS`, `ATMOS_ARTIFACTS_README`, `ATMOS_ARTIFACTS_CHANGELOG`, `ATMOS_ARTIFACTS_OUTPUT`, `ATMOS_ARTIFACTS_FROM`, `ATMOS_ARTIFACTS_TO`, `ATMOS_ARTIFACTS_REFRESH`, `ATMOS_ARTIFACTS_FORMAT`, `ATMOS_ARTIFACTS_YES`, `ATMOS_ARTIFACTS_INPUT`, and `ATMOS_ARTIFACTS_EXPECTED_DIGEST`. A command-line flag overrides its environment variable, which overrides the default.

## Authentication and CI

Repositories authenticate through Atmos Auth identities named in `artifacts.repositories.<alias>.identity`, so there is no separate login. Signing can prompt for Sigstore confirmation or identity-provider login. In CI, pass `--yes` or set `ATMOS_ARTIFACTS_YES` to accept confirmation; configure the identity provider for unattended authentication. Use [`--dry-run`](/cli/commands/artifacts/publish) to validate a publication without contacting a repository or resolving credentials.

## CI Summaries and Outputs

With [`ci.enabled: true`](/cli/configuration/ci), every `atmos artifacts` command that runs a repository operation appends one Markdown report to the CI job summary and writes the operation's results as CI output variables. The report covers published, unchanged, replaced, downloaded, copied, deleted, signed, verified, inspected, listed, and failed outcomes.

Each operation gets a row in an overview table and a section with:

- the outcome, the artifact reference, the repository, and the destination, with credentials and query strings removed so a presigned URL never reaches a summary
- the size and duration
- the digests, each labeled by what it identifies: the **resolved** digest (the OCI manifest or index, or the record for local and S3 repositories), the **record** digest, the **content** digest, and the **representation** digest (a transfer checksum)
- the lock that coordinated a mutation, stated as the scope that actually applied (`host` or `repository`) and what it does and does not exclude
- for `sign` and `verify`, the signature subject, the verified signer identities or key fingerprints, and the verification status

A report never blurs three distinctions. A digest or checksum proves that content is intact, not who published it. A **signed** artifact has evidence stored for it, but only a **verified** result means a trusted signer was authenticated. An **unchecked** result means no trust configuration was supplied, so nothing is claimed.

A failed operation is reported too, so a failed publish shows its error in the summary instead of only in the log. Reporting is best-effort. A template that cannot be loaded or a summary that cannot be written logs a warning and never changes the command's exit status or its JSON and YAML output on stdout. The report is only ever written to the CI summary file or, when no CI provider is detected, to stderr.

The CI output variables use the [named outputs](/steps/type/artifact#result) of the operation with an `artifact_` prefix: `artifact_ref`, `artifact_location`, `artifact_resolved_digest`, `artifact_record_digest`, `artifact_content_digest`, `artifact_representation_digest`, `artifact_size`, and `artifact_outcome`. A value the operation did not produce is omitted.

The summary and the outputs follow the existing CI switches: `ci.enabled`, `ci.summary.enabled`, `ci.output.enabled`, and an explicit CI mode such as `--ci`. With reporting disabled, Atmos makes no extra request to a repository. The report is built from the result the operation already returned. Pull request comments and commit checks are separate, opt-in CI features and are not written by artifact operations. Customize the report with [`ci.templates.artifacts`](/cli/configuration/ci/templates#artifacts).

The [`atmos artifacts catalog`](/cli/commands/artifacts/catalog) subcommands are the exception. They maintain a repository's discovery catalog, do not open a report session, and write neither a CI summary nor CI output variables.

## Workflows, Custom Commands, and Hooks

Every command except the [`atmos artifacts catalog`](/cli/commands/artifacts/catalog) subcommands also runs as an [`artifact` step](/steps/type/artifact) in a workflow, a custom command, an embedded script, or a `kind: step` lifecycle hook. The step calls the same implementation in process, so it needs no `atmos artifacts` subprocess, and it returns the result that `--format=json` prints under `metadata.artifact`, together with the named outputs `ref`, `location`, `resolved_digest`, `record_digest`, `content_digest`, `representation_digest`, `size`, and `outcome`. A workflow, a custom command, an embedded script, or a hook writes one [CI report](#ci-summaries-and-outputs) for all of its artifact operations after it ends, with retries collapsed to the final attempt.

```yaml
hooks:
  backup-output:
    events: [after.terraform.apply]
    kind: step
    type: artifact
    with:
      action: publish
      source: ./dist
      repository: backups
      artifact_name: backups/app
      version: build-123
```

## Subcommands

## Related

- [Artifacts Configuration](/cli/configuration/artifacts): repositories, identities, packaging, locking, and verification policy
- [Authentication](/cli/configuration/auth): identities used by `identity`
- [`artifact` step](/steps/type/artifact): run the same operations from workflows, custom commands, scripts, and hooks
