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 on this machine, registers the agent under your account by sending only the public key (from 1.7.0; earlier versions received a server-generated key once), 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.)--name <name>: set the agent’s name non-interactively--force: replace an existing agent’s key (a timestamped backup is written first)--owner <uuid>: register against a specific owner ID (legacy non-interactive path; usually unnecessary once you’re signed in). This path waits for the owner to approve the registration, and only it uses--scope <platform:scope>(repeatable),--no-waitand--timeout <seconds>(default 300)--json: machine-readable output
The agent is active as soon as it registers (no approval step on the signed-in path) and starts with no platform access; you grant platforms from the dashboard.
A user-scoped config (the default) points your IDE at the most recently registered agent. Registering again in another directory repoints ~/.claude.json, ~/.cursor/mcp.json and friends at the new agent; use --project if different directories need different agents.
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, --force.
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.
git-setup and git-credential
npx @agentvalet/register git-setupConfigures git to authenticate to the AgentValet proxy as this agent, so remotes of the form https://api.agentvalet.ai/git/<owner>/<repo>.git work with nothing but the agent key on disk. Writes to your global git config by default; --local writes to the current repository instead, and --print shows the git config command without running it.
git-credential is the credential helper that git-setup registers. Git calls it for you; it answers only for the proxy host, with a freshly signed agent token.
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, --force.
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.