# atmos artifacts catalog add

Resolve one or more releases and list them in the latest published catalog, creating the catalog when none exists. Only artifact metadata is read.

> ⚠️ Experimental

## Usage

```shell
atmos artifacts catalog add <ref>... --repository=<alias> [flags]
```

## Examples

```shell
# List one release
atmos artifacts catalog add components/terraform/vpc:1.2.0 --repository=shared

# List several releases in one write
atmos artifacts catalog add components/terraform/vpc:1.2.0 tools/helper:0.1.0 --repository=shared
```

## Behavior

Add takes the repository's lock when it provides one, reads the latest catalog, resolves each ref, lists it, and publishes the result with a new revision. A version that is already listed is updated when its tag now resolves to a different digest, and reported under `updated`.

## Arguments

- **`ref` (required, repeatable)** — `name:version` or `name@sha256:<digest>`, relative to the repository.

## Flags

- **`--repository`, `-r` (required)** — Configured repository alias. Its `catalog` setting selects the catalog.
  Environment variable: `ATMOS_ARTIFACTS_REPOSITORY`
- **`--format` (optional)** — Output format: `text` (default), `json`, or `yaml`.
  Environment variable: `ATMOS_ARTIFACTS_FORMAT`

## Errors

- **Catalog not configured** — The repository has no `catalog`. Nothing is written.
- **Reference not found** — A ref does not resolve in the repository. Nothing is written.
- **Catalog changed** — Another writer published between the read and the write. Run the command again, and run only one catalog writer at a time.

Every failure exits with a nonzero status.

## Related

- [`atmos artifacts catalog remove`](/cli/commands/artifacts/catalog-remove)
- [`atmos artifacts catalog sync`](/cli/commands/artifacts/catalog-sync)
- [Artifacts Configuration](/cli/configuration/artifacts)