# 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

## Usage

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

## Examples

```shell
# 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`](/cli/commands/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

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