Skip to main content

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
atmos artifacts list --help

Usage​

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

Examples​

# 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​