The venom CLI
How the venom command is organised, the ways to run it (terminal UI, print mode, JSON, RPC) and where each part of it is documented.
venom is a coding agent for the terminal. It is a distribution of pi: it starts pi's own command line with venom's extensions loaded (the permission engine, subagents, plan mode, the HUD and the rest) and sovereign defaults (no telemetry, no update checks, no calls to anything but the endpoint you configure). Everything pi's CLI accepts works, and venom adds its own subcommands, flags, slash commands and keys on top.
New to venom? Install it and run a first session with the CLI quickstart.
Ways to run it
venom # the terminal UI in this directory
venom "fix the failing test in api/" # the terminal UI, starting with a prompt
venom -p "explain this repo" # print mode: one answer on stdout, then exit
venom --mode json "list the TODOs" # JSON lines: every event, then exit
venom --mode rpc # JSON commands on stdin, events on stdout, until shutdown
venom -c # continue the newest session of this directory
venom doctor # check the setupWith a terminal on stdin and stdout, venom opens the terminal UI. When either is redirected and no --mode is given, it runs in print mode. Print, JSON and RPC modes covers scripting and CI.
Where things are
| Page | What it covers |
|---|---|
| Flags | every flag venom takes: venom's own (permission modes, worktrees, browser, budgets) and pi's (models, sessions, tools, resources) |
| Slash commands | every /command in a session, venom's and pi's |
| Keys | the leader key (ctrl+g), its bindings and the other shortcuts |
| The terminal UI | the HUD, the call meter, transcript verbosity, reading width, the agents panel, the pull requests pane, sounds and themes |
| Plan mode | read-only planning, the plan file and approving it |
| Print, JSON and RPC modes | headless runs, piped stdin, slash commands without a UI, --json on subcommands |
The subcommands that work outside a session are listed below. venom --help prints venom's commands, flags and environment variables first, then pi's help; venom <command> --help prints one command's usage.
Every subcommand
| Command | What it does | Documented in |
|---|---|---|
venom doctor, venom cost, venom usage, venom explain-cost, venom diet, venom stats, venom forecast, venom routes, venom flaky, venom models |
setup checks, spend, routing, waste, flaky tests, local models | Cost, health and routing commands |
venom init, venom explain, venom tour, venom ask, venom onboard, venom memory, venom index, venom lessons |
project setup, memory, onboarding | Project setup, memory and onboarding commands |
venom bisect, venom try, venom intent, venom provenance, venom revert, venom evidence, venom ship, venom stack, venom capture |
git, review and shipping | Git, review and shipping commands |
venom -c, venom resume, venom sessions, venom session, venom export, venom export-traces, venom attach, venom triage |
sessions | Sessions, resume and export |
venom workspace |
git worktrees venom made | Workspaces |
venom test-impact |
the tests a change can affect | The agent's tools |
venom theme, venom sounds |
colour themes, event sounds | The terminal UI |
venom config, venom gear |
the configuration and gears | Configuration |
venom trust, venom policy, venom audit, venom egress, venom secrets, venom actions, venom compliance, venom redteam, venom risk |
trust, policy, audit and risk scoring | Security |
venom do, venom inbox, venom digest, venom schedule, venom workflow, venom spec, venom replay, venom handoff, venom board, venom fleet, venom intake |
background agents and automation (venom resume is also there) |
the automation section |
venom review |
a read-only review of a diff, a GitHub pull request or a GitLab merge request | the automation section |
venom plugin, venom mcp, venom library, venom role, venom skills, venom new, venom template |
plugins, MCP servers, the team library, roles, skills, templates | the plugins section |
venom cloud |
Venom Cloud sign-in | the cloud section |
venom browser, venom acp |
the browser extension; the Agent Client Protocol for editors | the integrations section |
venom serve |
harness sessions over HTTP and Server-Sent Events for apps | the server API section |
venom eval, venom finetune |
the eval suite, fine-tuning datasets | the evals section |
Names venom shares with pi
venom keeps its state where pi would keep its own, under venom's names:
| pi | venom |
|---|---|
~/.pi/ |
~/.venom/ (VENOM_HOME) |
~/.pi/agent/ |
~/.venom/agent/ (VENOM_CODING_AGENT_DIR) |
~/.pi/agent/sessions/ |
~/.venom/agent/sessions/ (VENOM_CODING_AGENT_SESSION_DIR) |
a project's .pi/ |
.venom/ |
pi |
venom |
pi's package commands work under the venom name: venom install <source>, venom remove <source>, venom list, venom update and venom auth. pi's own config (which package resources load) is venom config packages, because venom config shows venom's configuration.
Exit codes
Subcommands follow one rule: 0 success, 1 a failure the command reports (a check that did not pass, a conflict, nothing found), 2 a usage error. A flag or endpoint your organisation's policy forbids stops the run before it starts, naming the policy file. A Node.js older than the supported version stops with its own message before anything loads.
In this section
- Flags: Every flag the venom command takes, venom's own and the ones it inherits from pi, with what each does and its default.
- Slash commands: Every slash command in a venom session, grouped by what it is for, with its arguments, plus the context commands in detail.
- Keys: The leader key (ctrl+g) and what each key after it does, the direct shortcuts venom adds, pi's own keys, and copying text out of the TUI.
- The terminal UI: What the venom TUI shows and how to change it, from the HUD, call meter, transcript verbosity and reading width to the agents panel, pull requests pane, attachments, sounds and colour themes.
- Plan mode: Have the agent investigate read-only and write a plan before it changes anything, then approve the plan and let it execute.
- Print, JSON and RPC modes: Run venom without the TUI, in scripts, CI and other programs, with one printed answer, a JSON event stream or an RPC loop, plus piped stdin, approvals and --json output from subcommands.
- Sessions, resume and export: Where venom keeps sessions, how to continue, resume, search, replay, export, share and attach to them, and how to find the ones that went wrong.
- Workspaces (git worktrees): Run a session or a subagent in its own git worktree, then merge, apply, open a pull request for or remove its work with venom workspace.
- The agent's tools: The tools the venom agent can call beyond reading, editing and running commands, when each is offered, what it can reach, and the tests it runs after edits.
- Cost, health and routing commands: The venom subcommands that check the setup and explain spend, routing, tool errors, wasted tokens, flaky tests and local models.
- Project setup, memory and onboarding commands: Set a project up for venom, keep its memory, index its code, and help new people learn a codebase with tours, explanations and answers that cite their sources.
- Git, review and shipping commands: Find the commit that broke a test, try a goal several ways at once, track intents, sign and verify who made a change, revert it, and ship a branch or a stack of them.