> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.

# Registry command reference

> Every registry command, shared flag, scope, and exit code.

Reference for the `registry` binary from `@atlanai/registry`. For what the tool
is and how installs are stored, start with
[the package manager guide](/plugins/references/registry-cli).

## Commands

### Manage

| Command | Aliases | What it does |
| - | - | - |
| `init` | | Create `registry.yml` for this project. |
| `add <source>` | | Install artifacts from a repository. |
| `remove <names>` | `rm` | Uninstall artifacts, touching only what was recorded. |
| `sync` | | Make this project match its manifest. Offline when the lock pins the ref. |
| `update [names]` | `upgrade` | Re-resolve refs and restage only what moved. |
| `use <source>` | | Print one artifact without installing it. |

### Inspect

| Command | Aliases | What it does |
| - | - | - |
| `list` | `ls` | Show what is installed, and from where. |
| `status` | | Check installed artifacts against the lock. |
| `discover <source>` | | Show what a repository publishes. |
| `why <name>` | | Explain where one artifact came from. |
| `targets` | | List harnesses and how each was detected. |

### Maintain

| Command | What it does |
| - | - |
| `doctor` | Check that this machine can install. |
| `cache dir` | Print the snapshot store path. |
| `cache size` | Report how much the store is using. |
| `cache prune` | Sweep unreferenced snapshots. |

## Sources

`add`, `use`, and `discover` accept:

| Form | Example |
| - | - |
| `owner/repo` | `registry add vercel-labs/agent-skills` |
| HTTPS URL | `registry add https://github.com/owner/repo` |
| SSH URL | `registry add git@github.com:owner/repo.git` |
| `file://` URL | `registry add file:///srv/shared-skills` |
| local directory | `registry add ./local-skills` |

Any form may be suffixed with `@tag`, `@branch`, or `@sha`:

```bash theme={null}
registry add owner/repo@v2.1.0
registry add owner/repo@main
registry add owner/repo@9f2c1ab
```

Pin a `@sha` when you need the install to be reproducible regardless of what
the branch does later.

## Shared flags

| Flag | What it does |
| - | - |
| `-t`, `--target` | Restrict to named harnesses. Repeatable, comma-separated, or `*` for all. `--agent` is an accepted alias. |
| `-s`, `--select` | Restrict to named artifacts. Repeatable. |
| `-g`, `--global` | Use the user scope. |
| `-p`, `--project` | Use the project scope. |
| `--scope <scope>` | Choose `user`, `project`, or `local` explicitly. |
| `-y`, `--yes` | Accept prompts. |
| `--all` | Do not narrow the selection. |
| `--dry-run` | Print the plan and stop. |
| `--frozen` | Fail if the lock would change. |
| `--force` | Overwrite a copy that was edited locally. |
| `--copy` | Place copies instead of links. |
| `--depth <n>` | Recursive scan depth. |
| `--full-depth` | Scan without a depth limit. |

`-t claude,cursor` and `-t claude -t cursor` mean the same thing.

These are global and work on every command:

| Flag | What it does |
| - | - |
| `--json` | Machine-readable output. |
| `--verbose` | Show each step. |
| `-h`, `--help` | Usage for the CLI or a command. |
| `-v`, `--version` | Print the version. |

<Note>
  `-s` is **selection**, matching `npx skills`. If you are coming from
  `npx plugins`, where `-s` means scope, use `-g`, `-p`, or `--scope` instead.
</Note>

## Scopes

| Scope | Flag | Manifest |
| - | - | - |
| user | `-g`, `--global` | `~/.registry/registry.yml` |
| project | `-p`, `--project` | `./registry.yml` |
| local | `--scope local` | `./registry.local.yml` (gitignored) |

Inside a project the default is `project`; outside one, `user`.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success. |
| `1` | Error. |
| `3` | Drift — installed artifacts do not match the lock. |
| `4` | Authentication required. |

These are a scripting contract. In CI, treat `3` as "someone changed an
artifact by hand" and `4` as "the credential needs renewing" — they are not
interchangeable failures.

## Artifact kinds

`plugin`, `skill`, `agent`, `command`, `hook`, `mcp`, `rule`, `lsp`.

`plugin` is the container kind: a directory the harness loads whole, keeping
the inline hooks and MCP servers its manifest declares. The vocabulary matches
the open-plugin conventions, so a repository written for `npx plugins` needs no
translation.

Harnesses accept different subsets — run `registry targets` to see what each
detected harness supports.

## Examples

Install only the skills you want, into one harness:

```bash theme={null}
registry add owner/repo -s meeting-brief -s release-notes -t claude
```

Check a repository before committing to it:

```bash theme={null}
registry discover owner/repo
registry use owner/repo -s meeting-brief
```

Verify a project in CI without letting it rewrite the lock:

```bash theme={null}
registry sync --frozen
```

Find out where something came from, then remove it:

```bash theme={null}
registry why meeting-brief
registry remove meeting-brief
```

Reclaim disk:

```bash theme={null}
registry cache size
registry cache prune
```

## Related

<CardGroup cols={2}>
  <Card title="Package manager guide" icon="box" href="/plugins/references/registry-cli">
    Scopes, storage layout, and keeping a project in sync.
  </Card>

  <Card title="atlanai CLI reference" icon="terminal" href="/tools/cli/references/commands/index">
    The other CLI — publishing to Agent Registry.
  </Card>
</CardGroup>