Operate Vruum

The agent operator's guide to Vruum — install the CLI, authenticate, connect the MCP server, and drive your full revenue lifecycle from the AI chat you already use.

Single source — do not fork. This is the ONE canonical reference for how an AI agent operates Vruum. Downstream surfaces read this file; they do not copy it. The three consumers are:

• llms-full.txt — the served, LLM-ingestible expansion of llms.txt.
• the /docs/agents page — the public docs route that renders this doc.
• VRU-501 vruum init — the harness instruction emitter (writeInstructions) that wires this doc into a project's AGENTS.md.

If you are about to paste this content somewhere, wire that surface to read OPERATE.md instead. A forked copy will drift; a backend drift guard (backend/tests/test_operate_doc.py) fails CI if this doc falls out of sync with the live sources of truth (the curated MCP tool set, vruum_exec, and the CLI command groups).

This is the customer/agent-facing sibling of the internal contributor guide AGENTS.md. AGENTS.md is for people building Vruum; OPERATE.md is for agents operating Vruum.

Vruum exposes its full revenue platform — pipeline, people, deals, outreach, marketing, knowledge base — to agents through two interchangeable surfaces that hit the same authorized backend endpoints under your own token:

1. The vruum CLI — a headless binary with machine-stable --json output on every command. Best for local agent harnesses, CI, and shell pipelines.
2. The MCP server — https://api.vruum.ai/mcp, a curated, default-loaded tool set plus a vruum_exec escape hatch that runs the same CLI server-side. Best for hosted MCP clients (Claude, ChatGPT, Cursor, …).

Neither surface can exceed your access: every call is authorized server-side by your token exactly as a normal user's would be.

1. Install & set up

Install the CLI

# npm (requires Node ≥ 22)
npm install -g @vruum/cli
# or run without installing
npx @vruum/cli --help

# Homebrew (macOS / Linux)
brew tap vruum-gtm/vruum && brew install vruum

# standalone binary (no Node)
curl -fsSL https://vruum.ai/install.sh | sh

Wire Vruum into your harness — vruum init

vruum init is the one-shot setup command. It detects every supported AI coding harness in the current project and, for each, registers the MCP (Bearer-authed against https://api.vruum.ai/mcp), links the client-safe skills, and writes instruction files that point the harness at this doc.

vruum login           # store your token first (see Auth below)
vruum init            # wire MCP + skills + instructions into detected harnesses
vruum init --project-dir /path/to/project

init reuses the token from vruum login and writes a static Authorization: Bearer MCP config (it avoids interactive-OAuth re-auth that drops hosted MCP connections mid-session). Restart your harness afterwards to load the Vruum MCP, then verify with a real tool call.

init is a local-CLI-only command — it writes config files on your host. It is deliberately not reachable through the server-side vruum_exec tool (see §4).

2. Authentication

vruum authenticates with a personal access token (PAT, vk_live_…). Generate one in the Vruum web app under Settings → API tokens.

# Interactive — prompts for the token (hidden) and stores it in ~/.vruum
vruum login
# Non-interactive — pass it or pipe it in
vruum login --token vk_live_xxx
echo "vk_live_xxx" | vruum login

vruum whoami          # confirm who you are authenticated as
vruum logout          # remove stored credentials

Environment variables

VRUUM_TOKEN makes the CLI fully stateless — ideal for CI and agent harnesses:

VRUUM_TOKEN=vk_live_xxx vruum deal list --json

login, logout, init, and the auth commands (whoami aside) are local-CLI only — they manage host credentials/config and are blocked from the server-side vruum_exec path, which injects your token for you.

Operating on behalf of a company — --for-company

Operators managing multiple tenants scope any command to one company:

vruum --for-company <company_id_or_exact_name> deal list

• On the CLI, --for-company is sent as the X-Company-Id header.
• Over MCP, the same intent is the for_company parameter. Resolution is by UUID or case-insensitive EXACT company-name match — partial/substring matches are NOT supported (an ambiguous name raises 400).
• Access is membership-enforced server-side: the value resolves to a user_company_id and the caller's membership in company_users is verified. A 403 means either the value matched no company or the caller is not a member of it. --for-company does not grant automatic operator powers — you get this access by being a member of each client company, the same row that grants any normal user access.

3. Calling Vruum from an agent

--json and exit codes

Every CLI command supports --json for stable, scriptable output. Without it, commands print human-readable tables; with it, JSON suitable for jq, agents, and CI.

vruum deal list --json | jq '.[] | select(.stage == "negotiation")'
vruum review outreach --json | jq '.items | length'

The process exit code is the agent's success signal:

Global flags

4. The MCP surface

The MCP server at https://api.vruum.ai/mcp advertises the full operation set (~139 tools) but default-loads a curated set to keep tool selection accurate and context small. Tools outside the default set are deferred, not removed — they stay advertised and callable; a Tool-Search-capable client keeps them out of the model's default context until discovered.

Default-loaded tools

The curated default set covers the full daily loop — briefing → review → message/plan management → deal updates → core CRM writes:

Tool Search (the deferred tail)

A Tool-Search-capable client (Anthropic Tool Search) registers the tool_search_tool_bm25_20251119 server-tool in its top-level tools array and mcp_toolset config. The model then BM25-searches the deferred tail at runtime instead of loading all ~139 tools into context. Where a client ignores the defer hint, nothing regresses — every tool stays loaded and callable.

vruum_exec — the full surface through one tool

vruum_exec is the escape hatch: it runs the bundled vruum CLI server-side under your own auth, giving any MCP client the entire Vruum surface through a single tenant-scoped tool — including the operations not in the default set.

• Pass args as the CLI argv array, never a shell string: ["deal", "list", "--json"], ["whoami", "--json"].

• Use --json inside args for machine-stable stdout. A non-zero CLI exit surfaces as a tool error carrying the CLI's stderr.

• for_company mirrors the operator multi-tenant UX (falls back to the request's X-Company-Id header when omitted).

• Blocked by design:

  • credential/host commands (login, logout, init, the auth commands) — the server injects your token; the CLI must not manage creds.
  • local-file ingestion (people import csv, ad creative upload, --content-file, @file args, absolute/~/.. host paths) — these read files off the server's filesystem.
  • the --api-url host-override flag — vruum_exec runs under the token the server injects, so the destination host is server-controlled. --api-url would redirect that authenticated call to an arbitrary host and exfiltrate your token, so it is rejected (the server resolves the API URL itself; VRUUM_API_URL cannot be set by the caller either).

  Run any blocked operation from the local CLI instead, where it acts under your own host and credentials.

5. The vruum command tree

Run vruum <group> --help for the flags of any subcommand. (Derived from the CLI source — cli/src/commands/*.command.ts — not from a hand-maintained list.)

Soft-delete-only: there is intentionally no deal delete or company delete. Deals retire via deal won / deal lost (revive with deal reopen); companies archive via their account state. History is never hard-removed.

6. Common agent workflows

All recipes below use only real, supported CLI surfaces. (Note: there is no vruum pipeline-fill command — pipeline-fill is a separate orchestration skill, not a CLI verb.)

Queue triage

# Review the three approval queues
vruum review outreach --json | jq '.items | length'
vruum review engagement --json
vruum review content --json
vruum review deals --json

# Approve every pending outreach message non-interactively
vruum message queue --json | jq -r '.[].id' | xargs -I{} vruum message approve {}

# Engagement queue: approve, edit, or skip individual items
vruum engagement queue --json
vruum engagement approve <id>
vruum engagement bulk-approve --ids id1,id2,id3   # max 100 ids/batch

Prospect import

# From a CSV (auto-detects columns) — local CLI only (file read)
vruum people import csv ./prospects.csv

# From a Sales Navigator list or saved search
vruum people import sales-nav --search "<saved search>"

# Manual single person + a note
vruum people create --first-name Ada --last-name Lovelace --company "Analytical Engines"
vruum people note <personId> "Met at the conference"

Deal operations

vruum deal list --json | jq '.[] | {name, stage, amount}'
vruum deal create --name "Acme expansion" --company <companyId>
vruum deal update <dealId> --amount 50000
vruum deal stage <dealId> negotiation
vruum deal stakeholder add <dealId> <personId> --role champion
vruum deal won <dealId>          # or: vruum deal lost <dealId>
vruum deal note <dealId> "Budget approved"

See also

• AGENTS.md — internal contributor guide (building Vruum, not operating it).
• cli/README.md — the CLI package readme.
• backend/app/mcp/server.py — DEFAULT_LOADED_TOOLS, VRUUM_EXEC_TOOL_NAME, TOOL_SEARCH_TOOL_TYPE (the live sources of truth this doc is guarded against).