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

cargo build --release -p agr   # → target/release/agr

Point it at a registry

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:

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

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.

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

agr install @fahrenheitresearch/weather-plugin --target claude

--target decides where files land:

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.

agr update              # list what changed upstream
agr update --yes        # re-resolve and write the updates

Uninstall

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)

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. --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 — the REST and MCP surfaces behind these commands
• Publishing — namespace ownership
• Operating the registry — running the crawler and scanner that populate it