@vruum/cli

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
job	get · list
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
revenue	status · metrics · evidence · bindings · connect · reconcile · replay · binding-decision · disconnect-preview · disconnect
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