CLI

Package: @valorbrain/cli. Runs without installing via npx -y @valorbrain/cli@latest <command>.

npx -y @valorbrain/cli@latest help --json

That JSON is the contract. If a blog post or README names a subcommand that is not in this object, the command does not exist. Every command and flag, generated from that JSON: CLI reference. This page explains the flow; it does not repeat the table.

The whole connection flow (token, MCP client, verify, claim) is in connect.md and the Quickstart.

Agent signup

npx -y @valorbrain/cli@latest init --agent --agent-caller <agent-name> --json

Creates an agent account (shadow tenant) with no email. With --json it prints a single JSON object with, among other fields:

Everything is saved to ~/.valorbrain/config.json (mode 0600); the other commands read it from there.

--agent-caller is self-declared, never inferred from the environment. Forgot it? npx -y @valorbrain/cli identify <agent-name> is the idempotent backfill.

Human claim

npx -y @valorbrain/cli init --email <email>

Binds the account to an email with a one-time code (OTP by email). After the claim the human sees the memories in the app and the account outlives 30 days. The api_key and the mcp_token do not change and keep working before and after. See Claim an agent account.

MCP stdio proxy

npx -y @valorbrain/cli mcp

Stdio ↔ Streamable HTTP proxy to https://mcpbrain.valor.digital/mcp. Use it as the server command in any MCP client that only speaks stdio:

{
  "mcpServers": {
    "valorbrain": {
      "command": "npx",
      "args": ["-y", "@valorbrain/cli", "mcp"]
    }
  }
}

It uses the token saved by init. --token <vbm_…> or VALORBRAIN_MCP_TOKEN override it; --url or VALORBRAIN_MCP_URL change the endpoint.

The MCP host accepts only vbm_. A vb_/vb_agent_ key as a bearer gets 401 wrong_credential_type. See MCP.

@valorbrain/connect is a different package: the optional installer that writes the MCP server, rules and hooks into your harnesses (npx -y @valorbrain/connect@latest --token <vbm_…>). It is not the stdio proxy.

Memory from the shell (REST)

add, search, list and status talk REST with the api_key:

npx -y @valorbrain/cli add "the deploy key lives in the ops vault"
npx -y @valorbrain/cli search "deploy key"

The body is stored verbatim — no translation. Flags for each command: CLI reference.

Environment variables

Order: flag (--api-key, --token, --url) → environment variable → ~/.valorbrain/config.json.

On-premise (Enterprise)

npx -y @valorbrain/cli --url https://your-engine.example.com init --agent

There is no public one-line installer for the engine. On-prem is an Enterprise plan — accompanied deployment by our team on your network.