# atmos artifacts catalog publish

Publish a catalog snapshot to the catalog configured on a repository. The command refuses to overwrite newer catalog metadata with a stale snapshot.

> ⚠️ Experimental

## Usage

```shell
atmos artifacts catalog publish <file> --repository=<alias> [flags]
```

## Examples

```shell
# Publish a built snapshot
atmos artifacts catalog publish catalog.json --repository=shared

# Publish only if the catalog is still the one the snapshot was built from
atmos artifacts catalog publish catalog.json --repository=shared --expected-digest=sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
```

## Behavior

Publish replaces the catalog's entries with the snapshot. Before it writes, it checks that the repository has a `catalog` configured, that every entry is bound to the repository path, and that the snapshot's revision equals the published catalog's revision. With `--expected-digest` it also checks the catalog's manifest digest. After a successful write the revision increases by one.

The write takes the repository's lock when the repository provides one, reads the latest catalog inside the lock, and checks the previous reference immediately before it moves the tag. Run only one catalog writer at a time. See [One writer at a time](/cli/commands/artifacts/catalog#one-writer-at-a-time).

## Arguments

- **`file` (required)** — A catalog snapshot written by `atmos artifacts catalog build`, in JSON or YAML.

## Flags

- **`--repository`, `-r` (required)** — Configured repository alias. Its `catalog` setting selects where the catalog is published.
  Environment variable: `ATMOS_ARTIFACTS_REPOSITORY`
- **`--expected-digest` (optional)** — Require the published catalog to have this manifest digest. Use the `base_digest` that `build` printed.
  Environment variable: `ATMOS_ARTIFACTS_EXPECTED_DIGEST`
- **`--format` (optional)** — Output format: `text` (default), `json`, or `yaml`.
  Environment variable: `ATMOS_ARTIFACTS_FORMAT`

## Output

Stdout carries `catalog`, the new `digest`, the `previous_digest`, `revision`, `listed`, `added`, and `lock_scope`.

## Errors

- **Catalog not configured** — The repository has no `catalog`. Nothing is written.
- **Catalog changed** — The published catalog has a different revision or digest than the snapshot expects. Rebuild the snapshot from the latest catalog.
- **Location outside the repository** — An entry names another registry, prefix, or path than the repository. Nothing is written.

Every failure exits with a nonzero status.

## Related

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