# CLI Reference (/docs/cli-reference) 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 --help` for the flags of any subcommand. ## Agent-safe pattern [#agent-safe-pattern] Ask agents to use this shape: ```text 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: ```sh 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 [#global-flags] | Flag | Description | | -------------------- | --------------------------------------------- | | `--json` | Emit machine-stable JSON instead of a table | | `--for-company ` | Scope the command to a company you can access | | `--api-url ` | Override the API base URL | | `-V, --version` | Print the version | | `-h, --help` | Show help for any command or subcommand | ## `--json` and exit codes [#--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 | ```sh 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 [#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 [#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 [#common-command-examples] People and pipeline: ```sh vruum people list --search "CFO" --limit 25 --json vruum people get --json vruum people import csv ./prospects.csv --campaign vruum people import sales-nav --list --limit 50 vruum people import sales-nav --saved-search --limit 50 ``` Outreach review: ```sh vruum review outreach --json vruum message approve vruum message reject vruum message edit --content "..." ``` Deals: ```sh vruum deal list --stage negotiation --json vruum deal create --person-id --name "Acme expansion" --value 50000 vruum deal update --value 75000 --next-step "Send pricing follow-up" vruum deal stage proposal vruum deal won vruum deal lost --reason "timing" --yes ``` Tasks and skills: ```sh vruum task list --json vruum task create --title "Follow up with Acme" --deal vruum skills list --json vruum skills show pipeline-fill ``` ## Notes grammar [#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: ```sh vruum people note "Met at SaaStr" # add vruum deal note "Budget approved" # add vruum deal note # list the deal's notes vruum deal note --limit 20 # list, capped (1-500) vruum deal note --delete # 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 [#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`. ## See also [#see-also] * [Getting Started](/docs/getting-started) — install, login, init, first call. * [Skills](/docs/skills) — workflow skill pages with MCP and CLI examples.