# 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
```