Registry command reference

Reference for the registry binary from @atlanai/registry. For what the tool is and how installs are stored, start with the package manager guide.

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:

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.

-s is selection, matching npx skills. If you are coming from npx plugins, where -s means scope, use -g, -p, or --scope instead.

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:

registry add owner/repo -s meeting-brief -s release-notes -t claude

Check a repository before committing to it:

registry discover owner/repo
registry use owner/repo -s meeting-brief

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

registry sync --frozen

Find out where something came from, then remove it:

registry why meeting-brief
registry remove meeting-brief

Reclaim disk:

registry cache size
registry cache prune

Package manager guide

Scopes, storage layout, and keeping a project in sync.

atlanai CLI reference

The other CLI — publishing to Agent Registry.

Get started

AI coding harnesses

Agent runtimes & frameworks

Commands

Manage

Inspect

Maintain

Sources

Shared flags

Scopes

Exit codes

Artifact kinds

Examples

Package manager guide

atlanai CLI reference

​Commands

​Manage

​Inspect

​Maintain

​Sources

​Shared flags

​Scopes

​Exit codes

​Artifact kinds

​Examples

​Related

Package manager guide

atlanai CLI reference

Commands

Manage

Inspect

Maintain

Sources

Shared flags

Scopes

Exit codes

Artifact kinds

Examples

Related