vruum

The headless CLI for the Vruum revenue platform — the universal floor for every agent harness. Drive your pipeline, deals, outreach, marketing, and knowledge base from the terminal or from any automation, with machine-stable --json output on every command.

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

Install

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

install script (standalone binary — no Node required)

curl -fsSL https://vruum.ai/install.sh | sh

The script detects your OS/arch, downloads the matching prebuilt binary from the latest GitHub release, verifies its SHA-256 checksum, and installs it to /usr/local/bin (falling back to ~/.local/bin). Re-running upgrades in place.

Prebuilt binaries are published for darwin-arm64, darwin-x64, linux-arm64, and linux-x64.

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 (input hidden) and stores it in ~/.vruum
vruum login

# Non-interactive: pass it explicitly or pipe it in
vruum login --token vk_live_xxx
echo "vk_live_xxx" | vruum login

# Confirm who you are authenticated as
vruum whoami

# Remove stored credentials
vruum logout

Environment variables

| Variable | Purpose | | ------------------ | ------------------------------------------------------------- | | VRUUM_TOKEN | PAT to use (overrides the stored credentials file) | | VRUUM_API_URL | Override the API base URL (default https://api.vruum.ai) | | VRUUM_CONFIG_DIR | Override the config/credentials directory (default ~/.vruum) |

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

VRUUM_TOKEN=vk_live_xxx vruum deal list --json

Operating on behalf of a company (operators)

Operators managing multiple tenants can scope any command to a company with the global --for-company flag:

vruum --for-company <company_id> deal list

Global flags

| Flag | Description | | -------------------- | ------------------------------------------------- | | --json | Emit machine-stable JSON instead of a table | | --for-company <id> | Act on behalf of a company (operator multi-tenant)| | --api-url <url> | Override the API base URL for this invocation | | -V, --version | Print the version | | -h, --help | Show help for any command or subcommand |

Command tree

Run vruum <group> --help for the flags of any subcommand.

| Group | Subcommands | | ------------ | -------------------------------------------------------------------------- | | account | get · set-stage · set-state · note | | ad | list · create · approve · reject · pause · resume · budget · creative upload | | campaign | list · get · create · update · clone · delete · members | | company | list · get · create · update | | content | list · create · edit · schedule · publish · delete | | cta | list · create · update · delete · set-default | | deal | list · get · create · update · stage · won · lost · reopen · note · stakeholder | | engagement | queue · approve · edit · skip · bulk-approve (max 100 ids/batch) · stats | | kb | list · show · upsert · reindex · delete | | message | queue · approve · reject · edit · regenerate · bulk-approve · bulk-reject · bulk-edit | | people | list · get · create · update · archive · note · import | | plan | get · start · pause · resume · stop · touch · override · channels | | proposal | list · get · create · draft · send · cancel | | review | outreach · deals · engagement · content | | settings | get · set | | skills | list · show | | task | list · create · complete · delete | | auth | login · logout · whoami |

Notes

people, account, and deal each expose a note command over the shared notes store (the canonical notes table / timeline read by the AI writer). All three share one grammar:

vruum people  note <personId>  "Met at SaaStr"   # add
vruum account note <companyId> "Renewal at risk" # add
vruum deal    note <dealId>    "Budget approved" # add

vruum deal note <dealId>            # list the deal's notes
vruum deal note <dealId> --limit 20 # list, capped (1-500)

vruum deal note --delete <noteId>   # delete by note id (no parent needed)

• A bare note with no parent id, no body, and no --delete is a usage error.
• --delete <noteId> takes precedence and is parent-agnostic — it deletes by the note's global id. Deletes are tenant-scoped server-side: a foreign or typo'd id reports not-found rather than silently succeeding.
• --limit accepts 1..500 (matching the backend contract).

deal note vs deal create/update --notes

These write to different places — don't confuse them:

• deal note <dealId> … reads/adds/deletes rows in the canonical notes table (the deal's free-text timeline, shared with people & accounts, surfaced to the AI writer). This is the agent-curatable note store.
• deal create --notes … / deal update --notes … sets the single deals.notes text field on the deal row itself — a one-off summary field, not a timeline. It is not listable or deletable via deal note.

Soft-delete-only: deals & companies

There is intentionally no deal delete or company delete verb — deals and companies are soft-delete-only by policy, so their history is never lost:

• Deals retire by recording an outcome: deal won / deal lost (and deal reopen to revive). The pipeline row and its full history are preserved for analytics and postmortems; there is no DELETE route to hard-remove a deal.
• Companies (accounts) archive via their account state rather than being hard-deleted, keeping the account anchor intact for the deals and people that reference it.

Individual notes can be hard-deleted (note --delete) — the policy above is about the deal/company records themselves, not their annotations.

--json examples

Every command supports --json for stable, scriptable output:

# Pipe deals through jq
vruum deal list --json | jq '.[] | {name, stage, amount}'

# Triage the outreach queue in a script
vruum review outreach --json | jq '.items | length'

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

# Snapshot the engagement queue for an agent
VRUUM_TOKEN=vk_live_xxx vruum engagement queue --json

Without --json, commands print human-readable tables; with it, they print JSON suitable for jq, agents, and CI.

License

MIT