Skip to main content

atmos artifacts search

Find artifacts by text across the configured repositories. The text matches names, kinds, descriptions, and labels, and each result names the repository alias it came from.

Experimental
atmos artifacts search --help

Usage​

atmos artifacts search [text] [--repository=<alias>] [--labels=<key=value>] [--refresh] [flags]

Examples​

# Search every configured repository
atmos artifacts search vpc

# Search one repository, filtered by labels, bypassing cached snapshots
atmos artifacts search vpc --repository=shared --labels='team=platform,purpose=backup' --refresh

# Machine-readable results
atmos artifacts search vpc --format=json

Behavior​

Search reads repositories and caches and never changes them, including catalogs. Without --repository, every configured repository is searched. Labels are exact key=value selectors, and every selector must match. Omitting the text returns every entry that satisfies the label selectors.

Arguments​

text (optional)

The text to match against names, kinds, descriptions, and labels.

Flags​

--repository, -r (optional)

Restrict the search 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 output has the same shape as atmos artifacts list: a table, or an artifacts array with a repositories array for json and yaml. An empty result is [] in structured output and No artifacts found. on stderr.

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​