# atmos plugin catalog add

Add a release’s verified metadata to a catalog.

> ⚠️ Experimental

## Usage

```shell
atmos plugin catalog add <catalog> <release-reference>
```

## Arguments and flags

- **catalog**
  A 
  plugins.registries
   alias that configures a 
  catalog
  , or an

  oci://
   catalog reference. A bare reference such as 
  registry.example.com/team/catalog:stable

  is rejected with a hint listing the usable aliases, and an alias without a 
  catalog
   is an error.
- **release-reference**
  OCI release reference that includes a version tag or a digest, with or without the 
  oci://

  prefix. A reference without a tag or digest is rejected before any registry request, because a registry
  would otherwise resolve an implicit 
  latest
   that a catalog must not pin.

Atmos reads the release from the registry, verifies that it is a plugin release, and adds its version to
the catalog entry. If the catalog does not exist yet, it is created.

## Publisher coordination

Run catalog mutations through one externally serialized maintainer workflow per catalog. The lock must cover reading the latest inputs, updating the snapshot, and publishing it. Revision and digest rechecks detect an already-stale update; they do not provide atomic compare-and-swap or prevent simultaneous writers from overwriting one another.

Plugin release jobs should publish artifacts independently. Use direct repository discovery when a collection does not need a curated catalog; see [plugin search](search.mdx).

## Examples

```shell
atmos plugin catalog add corporate oci://registry.example.com/team/oidc:0.1.0
atmos plugin catalog add oci://registry.example.com/team/catalog:stable oci://registry.example.com/team/oidc@sha256:<digest>
```