Register via the CLI

The CLI is how you bring an agent online from a terminal — in a project, on a server, in a CI job, anywhere you don’t have Claude Desktop’s GUI extension flow.

npx @agentvalet/register

That’s the whole command. Run it in the directory where the agent will live.

What happens when you run it

1. Authentication. A browser opens to /cli-auth on the AgentValet dashboard. You sign in if you haven’t already; you authorize the CLI; the CLI receives a session token over a localhost callback and keeps it in ~/.agentvalet/config.json, so later runs skip this step.
2. Agent name. The CLI asks for an agent name (defaults to <hostname> — <directory>; --name skips the prompt).
3. Registration call. The CLI generates an RS256 keypair on your machine and sends only the public key to AgentValet’s CLI registration endpoint, which returns the agent ID. (CLI versions up to 1.6.0 received a keypair generated on our side instead.)
4. Disk writes (see below).
5. Framework detection. The CLI looks for signs of Claude Code, Claude Desktop, Cursor, Codex, OpenClaw, or Factory Droid and, with your consent, configures whichever it finds.

There is no approval step: because you signed in, the agent is active as soon as it’s registered. It starts deny-by-default with no platform access; grant it platforms and scopes from its page in the dashboard.

What gets written to disk

./<project>/
  .agentvalet/
    agent.key       # RS256 private key (mode 0600)
    config.json     # agent_id, agent_name, proxy_url
  .env.agentvalet   # agent ID, owner ID, proxy URL, key path
  .claude/
    agentvalet-permissions.md    # human-readable summary of granted scopes
  CLAUDE.md                      # governance block added

~/.agentvalet/config.json        # your CLI sign-in (owner ID, session token)
~/.claude.json, ~/.cursor/mcp.json, ...   # MCP entries per detected framework

The private key lives in the project directory, and .agentvalet/ is added to .gitignore if the project has one. MCP configs are user-scoped by default; pass --project to write .mcp.json, .cursor/mcp.json and friends in the project instead. A user-scoped config points at one agent, so registering again in another directory repoints it at the newest agent.

Detected frameworks

The CLI prints the list of files it touched at the end of registration so you can verify.

Subcommands

After registration, you can re-invoke the CLI for maintenance:

• npx @agentvalet/register refresh — fetch the latest list of granted permissions and rewrite agentvalet-permissions.md
• npx @agentvalet/register mcp-server — run the AgentValet MCP server over stdio (the IDE configs above use this internally)
• npx @agentvalet/register list — list the agents registered under your account
• npx @agentvalet/register revoke — revoke an agent (and its child agents)
• npx @agentvalet/register inject — import an existing PEM private key for an agent into the local store and framework configs
• npx @agentvalet/register uninstall — request the agent’s revocation (the owner approves) and remove local files; --local-only skips the revocation request

See the CLI reference for every command and flag.

When the CLI is the wrong tool

If your only agent is Claude Desktop on your personal machine, the MCPB is simpler — drag-and-drop and you’re done, no terminal, no npm.

The CLI’s value is in everything else: codebases, CI, servers, multi-environment setups, IDEs that aren’t Claude Desktop. If that’s not your scenario, MCPB will save you steps.

Next

• Install paths compared
• Agent identity
• Get started in 5 minutes