# `agr` — the agent registry CLI
Find agent artifacts (Claude skills, `AGENTS.md` instructions, Cursor rules,
MCP servers) in a Saucebox registry and install them into a project.
`agr` is a plain HTTP client. It talks to a Saucebox gateway and never touches
a database, so it needs no local infrastructure.
## Install
```sh
cargo build --release -p agr # → target/release/agr
```
## Point it at a registry
| `AGR_REGISTRY_URL` | `https://api.saucebox.sirhco.codes` | Gateway base URL |
| `AGR_TOKEN` | (unset) | Bearer token — only needed for `publish` / `unpublish` |
Both have flag equivalents (`--registry`, `--token`) and are global, so they
work on any subcommand.
The default is the public registry, so a fresh `cargo install agr` needs no
configuration. Working against a local stack (`just up`) is what needs the
variable set:
```sh
export AGR_REGISTRY_URL=http://localhost:18080
```
Reading is anonymous: `search`, `info`, `install`, and `update` need no token
against a registry serving public artifacts.
## Find something
```sh
agr search weather
agr search pdf --type skill
agr search deploy --ecosystem claude
```
`--type` is one of `skill`, `agent`, `instructions`, `mcp-server`, `rules`.
`--ecosystem` filters by the tool that consumes the artifact (`claude`,
`copilot`, `codex`, `cursor`).
Results print as `@namespace/slug`, type, stars, and a truncated description.
Handles are normalized to lowercase — search output is authoritative, so copy
the handle from there rather than retyping the GitHub owner's casing.
```sh
agr info @fahrenheitresearch/weather-plugin
```
`info` prints the artifact plus its latest version as JSON — source repo,
pinned commit, ecosystems, license, and scan grade.
## Install into a project
```sh
agr install @fahrenheitresearch/weather-plugin --target claude
```
`--target` decides where files land:
| `claude` (skill) | `.claude/skills/<slug>/` |
| `claude` (agent) | `.claude/agents/<slug>.md` |
| `copilot` | `.github/copilot-instructions.md` |
| `codex` | `AGENTS.md` |
| `cursor` | `.cursor/rules/<file>`, or `.cursorrules` for the legacy single file |
`mcp-server` artifacts have no destination — an MCP server is registered in
your client's config rather than copied into a project, so `install` reports
that instead of writing files.
Other flags: `--dir` sets the install root (default: current directory), and
`--force` overwrites files that already exist.
Every install writes an `agr.lock` recording each file and the exact commit it
came from. Installing again is a no-op while the lockfile matches — it is safe
to re-run.
```sh
agr update # list what changed upstream
agr update --yes # re-resolve and write the updates
```
## Uninstall
```sh
agr uninstall @fahrenheitresearch/weather-plugin --target claude
```
Deletes exactly the files `agr.lock` recorded for that `(handle, target)` —
never a glob of the install directory — then drops the lockfile entry and
removes any directories the install left empty.
This reads only the lockfile, so it needs no network and keeps working after an
artifact is unpublished or the registry is unreachable.
An artifact you have edited since installing will not be deleted:
```
error: @acme/thing no longer matches what was installed; refusing to delete (use --force):
contents differ from the installed version
```
Pass `--force` to delete anyway. The same guard fires when some of the recorded
files are already gone by hand, since a partial install cannot be verified.
`--dir` sets the install root, as with `install`.
### What gets installed
The gateway builds the file list from the artifact's directory in its source
repo, pinned to a commit SHA — so an install is reproducible, not "whatever is
on `main` today".
**The listing is one level deep.** Files directly in the artifact's directory
are installed; files inside subdirectories are not. A skill that keeps helpers
in `tools/` installs its top-level files and silently omits that subtree.
## Publish (requires a token and a namespace grant)
```sh
export AGR_TOKEN=sb_live_...
agr publish @acme/my-skill \
--repo github.com/acme/my-skill \
--path skills/my-skill/SKILL.md \
--type skill \
--ecosystem claude \
--visibility public \
--description "What it does"
agr unpublish @acme/my-skill
```
Publishing requires two things that are checked independently:
1. The `registry:publish:@acme/*` scope on your bearer.
2. Your tenant owning the `@acme` namespace.
You can grant yourself a namespace by proving you control the matching GitHub
account — see [Publishing](../../docs/registry/PUBLISHING.md). `--ecosystem`
repeats for multiple targets. `--visibility` is `public`, `private`, or
`internal`.
## Exit behavior
Failures print the server's message and exit non-zero — a 409 on publish means
another tenant owns the namespace, a 403 means the scope or grant is missing.
## See also
- [Registry user guide](../../docs/registry/USER_GUIDE.md) — the REST and MCP
surfaces behind these commands
- [Publishing](../../docs/registry/PUBLISHING.md) — namespace ownership
- [Operating the registry](../../docs/registry/OPERATIONS.md) — running the
crawler and scanner that populate it