CLI reference
@agentvalet/register is the CLI (npx @agentvalet/register). It signs an agent up, generates its keypair, writes framework config, and manages the agent’s local credentials afterwards. This page documents every command it ships.
Run any command with --help for the full flag list; this page covers purpose and the flags you’ll actually reach for.
agentvalet-register (no subcommand)
The default action: interactive registration.
npx @agentvalet/registerSigns you in through your browser, generates an RS256 keypair, registers the agent under your account, and writes MCP config for whatever framework it detects in the current directory (Claude Code, Cursor, Codex, Factory Droid, OpenClaw). The private key is written to .agentvalet/agent.key in the project directory (with a .gitignore entry added automatically), and CLAUDE.md gets a governance snippet.
Key flags:
--project: write project-scoped configs (.mcp.json,.cursor/mcp.json, etc.) instead of the user-scoped default (~/.claude.json,~/.cursor/mcp.json, etc.)--no-frameworks: skip the IDE/framework config prompts--name <name>: set the agent’s name non-interactively--owner <uuid>: register against a specific owner ID (legacy non-interactive path; usually unnecessary once you’re signed in)--json: machine-readable output
refresh
npx @agentvalet/register refreshPulls the agent’s current granted-permissions list and rewrites .claude/agentvalet-permissions.md, so CLAUDE.md always reflects what’s actually approved. Run it any time an owner changes what an agent can do.
Flags: --output <path>, --if-stale (skip if the file is under an hour old), --quiet.
mcp-server
npx @agentvalet/register mcp-serverStarts the AgentValet MCP server over stdio. This is what your MCP config’s command/args actually invoke, you don’t normally run it by hand; your IDE or framework launches it for you.
list
npx @agentvalet/register listLists agents registered under your account, with ID, name, and status (active, suspended, revoked). Requires an authenticated CLI session (run the default command first if you haven’t signed in).
revoke
npx @agentvalet/register revoke --agent-id agt_...Revokes an agent. This cascades to every child agent it issued and cannot be undone; you’re asked to confirm. By default it also cleans local MCP config entries and key files for the revoked agent on this machine, pass --keep-local to skip that.
inject
npx @agentvalet/register inject --agent-id agt_... --key-file ./agent.pemImports an existing PEM private key (e.g. one copied from the dashboard, or generated by another machine) into the local store and framework configs, instead of generating a new keypair. Useful when you’re re-provisioning a machine for an agent that already exists.
Key flags: --owner-id <ownerId> (required for --target agentvalet), --target <agentvalet|env-local|claude-legacy> (where to write the key; agentvalet is the default modern store), --no-frameworks, --project.
uninstall
npx @agentvalet/register uninstallRequests the agent’s revocation (needs owner approval) and removes all local files: MCP config entries, CLAUDE.md/AGENTS.md governance blocks, the permissions file, and the key. Pass --local-only to skip the server-side revoke and just clean local files, or --timeout <seconds> to change how long it waits for approval.
install
npx @agentvalet/register install itok_...Binds an agent to this machine using a one-time install token (itok_...) generated from the dashboard, for example when a teammate is setting up a machine for an agent an admin already created. Generates the keypair locally, POSTs only the public key to the proxy, and writes the private key to ~/.agentvalet/agent.key (the global store, not project-local). Then runs the same framework-detection and config-writing flow as the default command.
Flags: --no-frameworks, --project.
claim
npx @agentvalet/register claim bsec_...Binds an agent from a one-shot invite secret (bsec_...) shown on the AgentValet claim page, the CLI counterpart to the invite flow. Generates a keypair locally and POSTs the public key to /v1/invites/bind.
Pass --label <name> to save the identity under ~/.agentvalet/<label>/ instead of the default ~/.agentvalet/, this supports multi-agent machines, for example claiming a work invite without overwriting an agent you already have installed.