CLI Reference

Every vruum CLI command group and subcommand, the global flags, --json output, and exit codes.

The vruum CLI is the technical fallback for local harnesses, CI, local files, and debugging. It drives pipeline, deals, outreach, marketing, tasks, proposals, team skills, and knowledge base from the terminal with machine-stable --json output.

Use MCP and skills for normal agent operation. Use the CLI when MCP is unavailable, when setup requires vruum init, when you need local files, or when a script needs deterministic stdout and exit codes. The CLI currently ships through npm/npx and requires Node 22 or newer; there is no Brew installer.

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

Agent-safe pattern

Ask agents to use this shape:

Use `vruum ... --json` for reads, parse stdout as JSON, and treat the exit code
as the success signal. Before writes, fetch the target object or queue and
summarize the evidence.

Examples:

vruum whoami --json
vruum deal list --json | jq '.deals[] | {id, deal_name, stage, estimated_value}'
vruum review outreach --json | jq '.items | length'
vruum skills list --json

Global flags

Flag	Description
`--json`	Emit machine-stable JSON instead of a table
`--for-company <id>`	Scope the command to a company you can access
`--api-url <url>`	Override the API base URL
`-V, --version`	Print the version
`-h, --help`	Show help for any command or subcommand

`--json` and exit codes

Without --json, commands print human-readable tables; with it, they print JSON suitable for jq, agents, and CI. The process exit code is the agent's success signal:

Exit	Meaning
`0`	Success
`3`	Auth failure — `401` Unauthorized / `403` Forbidden
`2`	Other `4xx` (usage / validation / not-found)
`1`	`5xx` server error or network failure

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

Some list commands return an envelope ({deals, count}), while others return arrays or queue objects. Agents should inspect the returned JSON shape before writing a long pipeline.

When CLI is required

Use the local CLI instead of MCP for:

Technical local setup with vruum login, vruum logout, and vruum init.
Local file reads such as vruum people import csv ./prospects.csv.
Shell pipelines with jq, xargs, or CI.
Auth debugging with vruum whoami --json.
Any workflow where the harness has not loaded the Vruum MCP server yet.

Command tree

Group	Subcommands
`account`	`get` · `set-stage` · `set-state` · `note`
`ad`	`list` · `create` · `approve` · `reject` · `pause` · `resume` · `budget` · `creative upload`
`auth`	`login` · `logout` · `whoami` (top-level; `login`/`logout` are local-CLI only)
`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` (`list`/`add`/`update`/`remove`)
`engagement`	`queue` · `approve` · `edit` · `skip` · `bulk-approve` · `stats`
`init`	(no subcommands — wires MCP + skills + instructions into detected harnesses)
`kb`	`list` · `show` · `search` · `upsert` · `reindex` · `delete`
`message`	`queue` · `approve` · `reject` · `edit` · `regenerate` · `bulk-approve` · `bulk-reject` · `bulk-edit`
`people`	`list` · `get` · `create` · `update` · `archive` · `note` · `import` (`csv` / `sales-nav`)
`plan`	`get` · `start` · `pause` · `resume` · `stop` · `touch` · `override` · `channels`
`proposal`	`list` · `get` · `create` · `draft` · `send` · `cancel`
`review`	`outreach` · `deals` · `engagement` · `content`
`settings`	`get` · `set` · `team` (`members` / `invite` / `join`)
`skills`	`list` · `show`
`task`	`list` · `create` · `complete` · `delete`

Common command examples

People and pipeline:

vruum people list --search "CFO" --limit 25 --json
vruum people get <person_id> --json
vruum people import csv ./prospects.csv --campaign <campaign_id>
vruum people import sales-nav --list <sales_nav_list_id> --limit 50
vruum people import sales-nav --saved-search <sales_nav_saved_search_id> --limit 50

Outreach review:

vruum review outreach --json
vruum message approve <message_id>
vruum message reject <message_id>
vruum message edit <message_id> --content "..."

Deals:

vruum deal list --stage negotiation --json
vruum deal create --person-id <person_id> --name "Acme expansion" --value 50000
vruum deal update <deal_id> --value 75000 --next-step "Send pricing follow-up"
vruum deal stage <deal_id> proposal
vruum deal won <deal_id>
vruum deal lost <deal_id> --reason "timing" --yes

Tasks and skills:

vruum task list --json
vruum task create --title "Follow up with Acme" --deal <deal_id>
vruum skills list --json
vruum skills show pipeline-fill

Notes grammar

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

vruum people  note <personId>  "Met at SaaStr"     # 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

deal note (the canonical notes timeline) is distinct from deal create/update --notes (the single deals.notes summary field on the deal row) — they write to different places.

Soft-delete-only: deals & companies

There is intentionally no deal delete or company delete verb. Deals retire via deal won / deal lost (revive with deal reopen); companies archive via their account state. History is never hard-removed. Individual notes can be hard-deleted with note --delete.