# atmos artifacts list

List the artifacts and versions that your repositories hold. Without `--repository`, every configured repository is listed and each entry names the alias it came from.

> ⚠️ Experimental

## Usage

```shell
atmos artifacts list [name] [--repository=<alias>] [--labels=<key=value>] [--refresh] [flags]
```

## Examples

```shell
# List every artifact in a repository
atmos artifacts list --repository=shared

# List the versions of one artifact
atmos artifacts list components/terraform/vpc --repository=shared

# List across all configured repositories, filtered by labels
atmos artifacts list --labels=team=platform

# List two repositories as JSON
atmos artifacts list --repository=shared,backups --format=json
```

## Behavior

List reads repositories and never changes them. Entries are sorted by name and then version. A repository that cannot enumerate its collection, or that fails to refresh, is reported under `repositories` in the structured result and as a message on stderr, so a missing result is explained rather than silent.

Labels are exact `key=value` selectors. An entry is kept only when every selector matches exactly.

## Arguments

- **`name` (optional)** — An exact artifact name. Restricts the listing to the versions of that artifact.

## Flags

- **`--repository`, `-r` (optional)** — Restrict the listing to these repository aliases. Accepts a comma-separated list or repeated flags. Defaults to all configured repositories.
  Environment variable: `ATMOS_ARTIFACTS_REPOSITORY`
- **`--labels` (optional)** — Exact `key=value` selectors, comma-separated and/or repeated. `key:value` is also accepted.
  Environment variable: `ATMOS_ARTIFACTS_LABELS`
- **`--refresh` (optional)** — Bypass cached discovery snapshots.
  Environment variable: `ATMOS_ARTIFACTS_REFRESH`
- **`--format` (optional)** — Output format: `table` (default), `json`, `yaml`, `csv`, or `tsv`.
  Environment variable: `ATMOS_ARTIFACTS_FORMAT`

## Output

The table shows the repository alias, name, version, kind, description, and labels. When piped, the table becomes plain tab-separated rows. `json` and `yaml` return an `artifacts` array, which is `[]` when nothing matches, and a `repositories` array with the per-repository counts and diagnostics. Each entry carries `repository`, `ref`, `name`, `version`, `kind`, `description`, `labels`, `documents`, `resolved_digest`, `record_digest`, `content_digest`, and the `pinned` reference that a consumer lockfile can store.

When nothing matches, stderr reports `No artifacts found.`, or says that no repositories are configured.

## Errors

- **Unknown repository alias** — Fails with an invalid artifact configuration error that lists the configured aliases.
- **Malformed label** — A selector without `=` or `:` fails before any repository is read.
- **Unsupported format** — `text` is not a collection format. Use `table`, `json`, `yaml`, `csv`, or `tsv`.

Every failure exits with a nonzero status. For failures reached while the command runs, `--format=json` or `--format=yaml` still writes the envelope to stdout with an empty `artifacts` array and an `error` field. Argument and flag parsing failures, such as an unknown flag or an extra argument, are rejected before the command runs and do not produce a structured envelope.

## Related

- [`atmos artifacts search`](/cli/commands/artifacts/search)
- [`atmos artifacts inspect`](/cli/commands/artifacts/inspect)
- [Artifacts Configuration](/cli/configuration/artifacts)