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

# 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/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/registry-cli">
    Scopes, storage layout, and keeping a project in sync.
  </Card>

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