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

## 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`, and `ATMOS_ARTIFACTS_YES`. 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.

## Subcommands

## Related

- [Artifacts Configuration](/cli/configuration/artifacts): repositories, identities, packaging, locking, and verification policy
- [Authentication](/cli/configuration/auth): identities used by `identity`