# atmos plugin registry add

Configure a registry host, repository discovery, or an optional catalog.

> ⚠️ Experimental

## Usage

```shell
atmos plugin registry add <name> [catalog] [--host=<host>] [--repository=<repository>] [--identity=<auth-identity>]
```

The command writes `plugins.registries.<name>` in the project's root `atmos.yaml`. It edits only that
entry, so comments, blank lines, and the rest of the file are preserved.

Adding a name that already exists **replaces the whole entry**. Keys you do not pass again, such as an
earlier `identity` or `repositories` list, are removed, and Atmos prints a warning that names what was
replaced. Use `atmos plugin registry list` before you overwrite an entry.

## Arguments and flags

- **name** — Local registry alias. Lowercase letters, digits, hyphens, and underscores, starting with a letter.
- **catalog** — Optional OCI reference for a published discovery snapshot. Alternatively, use --catalog.
- **--catalog** — Optional catalog reference, equivalent to the positional catalog argument. Do not supply both.
- **--host** — Registry authority, such as registry.example.com or localhost:15557. When omitted, it is inferred from the discovery inputs. All inputs must use the same host. A host-only entry can configure authentication without discovery.
- **--repository** — OCI repository without a tag or digest. Repeat to index multiple repositories locally. Can coexist with a catalog; no shared catalog maintenance is required.
- **--identity, -i** — Name of an identity in auth.identities used to authenticate to the registry host. This is the
  global Atmos --identity flag, so the ATMOS\_IDENTITY environment variable also
  selects it; an explicit flag takes precedence. The identity must exist, and a value-less
  -i (interactive selection) is rejected because a registry binds to one named identity.
  \--identity=false or ATMOS\_IDENTITY=false means no identity. The binding applies to plugin
  releases, discovery, publishing, and signatures on that host. Without an identity, Atmos records
  auth: docker and uses the shared Docker and stored-credential chain (see
  credential precedence).

## Examples

```shell
atmos plugin registry add team --host=registry.example.com --repository=oci://registry.example.com/team/oidc --repository=oci://registry.example.com/team/credentials --identity=registry-reader
atmos plugin registry add corporate oci://registry.example.com/team/catalog:stable --identity=registry-reader
atmos plugin registry add publisher --host=publishing.example.com --identity=publisher
ATMOS_IDENTITY=registry-reader atmos plugin registry add corporate oci://registry.example.com/team/catalog:stable
```