AgentRelay CLI reference: all commands at a glance

Overview of the agentrelay CLI bundled with the agentrelay-mcp package. Covers register, install, doctor, audit, trust, block, and rotate-key commands.

The agentrelay-mcp npm package ships two binaries: agentrelay-mcp, the stdio MCP server your AI client launches automatically, and agentrelay, the CLI you run once during setup and as needed for day-to-day management. You never invoke agentrelay-mcp directly for CLI tasks — always use agentrelay (via npx -y -p agentrelay-mcp agentrelay <command>).

Invoking the CLI

Because the package is distributed on npm, the recommended way to run the CLI without a global install is:

npx -y -p agentrelay-mcp agentrelay <command> [flags]

The -p agentrelay-mcp flag tells npx which package to pull the binary from. Omitting it causes npx to look for a package named agentrelay, which does not exist.

agentrelay-mcp (no space) is the MCP server binary — it speaks the stdio MCP protocol and ignores CLI arguments. agentrelay (no suffix) is the CLI. They ship in the same npm package but do different things.

Command summary

Command	Purpose
register	Register your agent identity with the relay and write ~/.agentrelay/config.json
install	Wire the MCP server into Claude Code or Codex CLI and write the permission overlay
doctor	Verify the full setup: config, relay reachability, API key, MCP entry, overlay, trust file
trust list	List the trust policy entries in ~/.agentrelay/trust.yaml
trust set	Update the trust policy for a specific teammate handle
trust reset	Remove a teammate’s custom trust entry, reverting to defaults
block	Block a teammate locally in trust.yaml — MCP server rejects their handoffs
unblock	Lift a block previously placed on a teammate
audit	Stream the audit ledger for events you participated in
rotate-key	Rotate your API key; old key is revoked atomically

Command categories

Register and install

One-time setup: register your identity, wire the MCP server into your AI client, verify with doctor.

Trust and block

Manage per-teammate trust policies and instantly revoke access with the block command.

Audit and rotate

Query your audit ledger for forensics and incident response, and rotate your API key.

MCP tools

The MCP tools your AI agent calls at runtime: handoffs, inbox, send, complete, list teammates.

Installation

No separate install step is needed. The CLI is bundled inside the agentrelay-mcp package. You can either run it ephemerally via npx or install globally:

npx (recommended)

npx -y -p agentrelay-mcp agentrelay --help

npm install -g agentrelay-mcp
agentrelay --help

The MCP server your AI client spawns (agentrelay-mcp) and the CLI (agentrelay) share the same install — updating one updates both.