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

Authentication. A browser opens to /cli-auth on the AgentValet dashboard. You sign in with Clerk if you haven’t already; you authorise the CLI; the CLI receives a session token over a localhost callback.
Interactive wizard. The CLI asks for an agent name (defaults to <hostname> — <directory>) and walks you through optional scope requests.
Framework detection. The CLI looks for signs of Claude Code, Cursor, Codex, OpenClaw, or Factory Droid in the current project and home directory. Whichever it finds, it’ll configure.
Registration call. It hits the proxy’s /v1/cli/register-agent endpoint, which generates an RS256 keypair and returns the agent ID + private key.
Disk writes (see below).
Pending approval. The agent is created in status: pending until you approve the registration in the dashboard. The CLI tells you to do this and waits.

Once you approve, the agent is active and any IDE you configured in step 5 can call AgentValet tools.

What gets written to disk


~/.agentvalet/
  agent.key         # RS256 private key (mode 0600)
  config.json       # agent_id, owner_id, proxy_url

./<project>/
  .claude/
    agentvalet-permissions.md    # human-readable summary of granted scopes
  .mcp.json                       # if Claude Code detected
  .cursor/mcp.json                # if Cursor detected
  ...etc per detected framework
  .env.agentvalet                 # optional, for shell env injection

The home-directory key is canonical; project-level keys are written only when needed. The CLI refuses to overwrite an existing key without explicit confirmation.

Detected frameworks

Framework	Detection signal	Files written
Claude Code	`.claude/` dir or `claude` binary	`.mcp.json` (project) or `~/.claude.json` (user fallback)
Cursor	`.cursor/` dir or Cursor app	`.cursor/mcp.json`
Codex	`~/.codex/` or `codex` binary	`~/.codex/config.toml`
OpenClaw	`~/.openclaw/`	OpenClaw MCP config
Factory Droid	`.factory/` dir	`~/.factory/mcp.json`, `.factory/droids/` entries

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 — show locally-registered agents
npx @agentvalet/register revoke — revoke an agent
npx @agentvalet/register inject — write env-var exports to .env.agentvalet for shell sourcing
npx @agentvalet/register uninstall — remove local config (does not delete the agent on the server; use revoke for that)

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.