Navigate

Tools

$ agent-root

CLI and MCP server for searching, installing, and publishing AgentRoot records. The CLI is DNS-first: discover, install, update, and uninstall all work without depending on the central registry.

// cli

CLI

Install

The package is @agent-root/cli on npm. The installed binary is agent-root (with agentroot as an alias) no matter how you install it. Requires Node.js 18 or later.

# Global install
$ npm install -g @agent-root/cli
$ agent-root help

# One-off without installing
$ npx -p @agent-root/cli agent-root help

Commands

Per-command help via agent-root <cmd> --help on every command listed below.

// discover

Command	Arguments	What it does
`resolve`	`<domain>[/<record-id>]`	DNS-first lookup. Fetches the manifest and lists records.
`search`	`<query>`	Search the public registry. Filter by record type (--type=agent\|mcp\|skill\|a2a\|payment). Paginate with --page/--limit, or fetch all matches with --all.

// install

Command	Arguments	What it does
`install`	`<domain>/<record-id>`	Install a record. Flags: --tool, --project, --all.
`list`	—	Show every record installed on this machine.
`update`	`<domain>/<record-id>`	Re-fetch from source. Hash-compares; writes only on change.
`uninstall`	`<record-id>`	Remove an installed record.

// publish

Command	Arguments	What it does
`init`	`[path]`	Scaffold a .well-known/agentroot.json starter.
`validate`	`<file>`	Validate a LOCAL JSON file against the manifest schema.
`submit`	`<domain>`	Submit a domain to the registry. Local DNS probe + POST /api/submit.

// registry

Command	Arguments	What it does
`health`	—	Probe /api/health. Non-zero exit if the registry is unhealthy.
`manifests`	—	Paginated browse of /api/manifests. Same flags as search.
`collections`	`[<slug>]`	List curated collections, or open one by slug.

// tooling

Command	Arguments	What it does
`version`	—	Print version, Node, OS, API base, config path. Paste into bug reports.
`completion`	`<shell>`	Print bash \| zsh \| fish \| pwsh completion script to stdout.
`config`	`get \| set`	Inspect or change ~/.agentroot/config.json.
`help`	`[command]`	Top-level help, or `agent-root <cmd> --help` for per-command help.

Search & filter examples

Discovery, search, and filtering all live on agent-root search (registry-wide) and agent-root resolve (single domain via DNS). There is no separate discover-skills binary. To filter results, use --type with one of the five record types — the CLI accepts a single value per call:

# every skill matching "weather"
$ agent-root search "weather" --type=skill

# every MCP server in the catalog (empty query, fetch all pages)
$ agent-root search "" --type=mcp --all

# second page of A2A endpoints matching "payments", 20 per page
$ agent-root search "payments" --type=a2a --page=2 --limit=20

# every record (skill, agent, mcp, ...) registered under one domain
$ agent-root resolve example.com

Valid --type values: agent, mcp, skill, a2a, payment. Filtering by capability substring, author domain, or semantic tags isn't a CLI flag today — use the REST endpoint GET /api/records?q=&type=&capability=&domain= directly, or pipe --json output through jq.

Flags

Flags accept kebab-case (--manifest-url) or camelCase (--manifestUrl), and either --key value or --key=value. Pass -- to stop option parsing. Any boolean accepts negation via --no-<flag>.

Flag	Description
`--help, -h`	Show help (or per-command help for `agent-root <cmd> --help`)
`--version, -v`	Print version on one line
`--json, -j`	Output as JSON (single envelope on errors too)
`--yes, -y`	Auto-confirm all prompts (for CI / scripts)
`--force, -f`	Overwrite existing files
`--quiet, -q`	Suppress spinners and non-essential notes
`--tool <name>`	Target tool: claude \| cursor \| codex \| gemini \| agents
`--type <type>`	Filter by record type: agent \| mcp \| skill \| a2a \| payment
`--project`	Install to current directory (not home)
`--all`	Install every record, or fetch every search/manifests page
`--page <N>`	1-indexed page number for search/manifests (default 1)
`--limit <N>`	Per-page limit, 1..100 (default 20)
`--query <q>`	Free-text filter for manifests
`--manifest-url`	Explicit manifest URL for submit (skip DNS probe)
`--domain <name>`	Domain name for init template
`--no-install`	Skip auto-install when resolving skill= records
`--no-color`	Disable ANSI color (also auto-off in non-TTY)

Install paths by tool

Install puts files in a canonical store under ~/.agents/skills/<domain>/<record-id>/, then creates a symlink (or copy with --project) into your tool's expected location:

Tool	Global (default)	Project (with `--project`)
`claude`	`~/.claude/skills/<domain>/<record-id>/`	`.claude/skills/<domain>/<record-id>/`
`cursor`	`— (no global support)`	`.cursor/skills/<domain>/<record-id>/`
`codex`	`~/.codex/skills/<domain>/<record-id>/`	`.agents/skills/<domain>/<record-id>/`
`gemini`	`~/.gemini/skills/<domain>/<record-id>/`	`.agents/skills/<domain>/<record-id>/`
`agents`	`~/.agents/skills/<domain>/<record-id>/`	`.agents/skills/<domain>/<record-id>/`

agents (the default if you skip --tool) is a single, tool-neutral install that any AgentRoot-aware tool picks up. cursor only supports --project.

Note: install never mutates your AI tool's settings JSON. There is no automatic write to mcp.json, settings.json, or .cursorrules. For MCP servers, the CLI prints the config snippet you should paste into the right file yourself.

Output streams + --json

Spinners, progress notes, and chatter go to stderr. Data and --json output go to stdout. agent-root <cmd> --json | jq works without 2>/dev/null.

In --json mode, errors emit a single envelope on stdout. Exit code and error.code always agree, so scripts can branch on both:

$ agent-root resolve nonexistent.test --json
{
  "error": {
    "code": "NOHOST",
    "message": "No _agentroot.nonexistent.test TXT record found",
    "hint": "Try: agentroot search nonexistent"
  }
}
$ echo $?
68

Exit codes

Sysexits-style. Source: man 3 sysexits.

Code	Name	Meaning
`0`	`OK`	Success
`1`	`GENERIC`	Unspecified error
`2`	`USAGE`	Bad arguments: unknown command, missing positional, conflicting flags
`66`	`NOINPUT`	File not found (validate /nonexistent, init without --force when file exists)
`68`	`NOHOST`	DNS lookup failed, no _agentroot TXT record, domain not in registry
`69`	`UNAVAILABLE`	Registry unreachable, manifest fetch failed, network 5xx
`76`	`PROTOCOL`	Manifest validation failed against the protocol schema
`77`	`NOPERM`	Permission denied writing to ~/.agentroot or ~/.claude/skills
`78`	`CONFIG`	Configuration error (installed record missing source_url, corrupted state)

Environment variables

Precedence: explicit flag > namespaced env > standard env > CI default.

Variable	Effect
`NO_COLOR=1`	Disable ANSI color (no-color.org convention)
`FORCE_COLOR=0`	Disable ANSI color (Node convention)
`CI=true`	Imply --yes and --no-color (no prompts, plain text)
`AGENTROOT_YES=1`	Imply --yes
`AGENTROOT_JSON=1`	Imply --json
`AGENTROOT_NO_COLOR=1`	Imply --no-color (namespaced variant)
`AGENTROOT_API_BASE=<url>`	Override the registry API base

Shell completion

Completes commands, flags, and value enums for --tool and --type:

# bash
$ agent-root completion bash > /usr/local/etc/bash_completion.d/agent-root

# zsh
$ agent-root completion zsh > "${fpath[1]}/_agent-root"

# fish
$ agent-root completion fish > ~/.config/fish/completions/agent-root.fish

# PowerShell
$ agent-root completion pwsh > $PROFILE.CurrentUserAllHosts/agent-root.ps1

Typo suggestions

Unknown commands trigger a Levenshtein-based hint:

$ agent-root reslove doma.xyz
error Unknown command: reslove
       Did you mean: agentroot resolve?

Release notes: CHANGELOG.md. Current release is 0.3.0.

// mcp_server

MCP Server

@agent-root/mcp-server gives MCP-aware clients direct access to the registry: search, inspect manifests, install records — all from inside the AI conversation, without leaving the chat to run a CLI command.

Install

The installed binary is agentroot-mcp-server. Run via npx, or install globally:

# One-off
$ npx -p @agent-root/mcp-server agentroot-mcp-server

# Global
$ npm install -g @agent-root/mcp-server
$ agentroot-mcp-server

Tools

11 tools are registered with the server:

Tool	What it does
`resolve_domain`	DNS-first discovery. Resolves _agentroot.<domain> TXT and returns every v=ar1 record. Skills auto-install unless no_install=true.
`search_records`	Search the registry across all types. Args: query, type (agent \| mcp \| skill \| a2a \| payment), verified_only.
`search_skills`	3-tier search fallback (discover → find-skills → manifests). Args: query, verified_only.
`get_manifest`	Full manifest for a domain: all records, subdomains, verification status. Arg: domain.
`get_zone`	[DEPRECATED — use get_manifest] Same shape, retained for back-compat.
`install_record`	Install any record. Call search first and pass back domain + record_id verbatim. Args: domain, record_id, tool?.
`install_skill`	Skill-only install. Same args as install_record.
`list_installed`	Scan tool dirs and list every AgentRoot record installed locally. No args.
`read_skill`	Read installed SKILL.md (or a supporting file). Args: record_id, file?.
`update_record`	Re-fetch SKILL.md. Hash-compares; only writes on change. Skill-type only. Args: domain, record_id, tool?.
`uninstall_record`	Remove a record from one tool or all. Args: record_id, tool?.

Claude Code

Add to .claude/mcp.json (project) or ~/.claude/mcp.json (global):

{
  "mcpServers": {
    "agentroot": {
      "command": "npx",
      "args": ["-p", "@agent-root/mcp-server", "agentroot-mcp-server"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "agentroot": {
      "command": "npx",
      "args": ["-p", "@agent-root/mcp-server", "agentroot-mcp-server"]
    }
  }
}

// next

← API Reference

Install with Claude Code →