Every flag the venom command takes, venom's own and the ones it inherits from pi, with what each does and its default.
Flags go before or after the prompt: venom --yolo "fix the build" and venom "fix the build" --yolo are the same. -- ends option parsing, so a prompt may start with a dash: venom -p -- "- summarise these points". Subcommands (venom cost, venom workspace, ...) take their own flags, documented with each command.
venom --permission-mode accept-edits -w fix-login "make the login test pass"
venom --plan "how would we split the billing module?"
venom -p --output-budget 20000 --no-self-review "refactor src/cache.ts and open a PR"
Permissions and sandbox
| Flag |
What it does |
--permission-mode <mode> |
Start in this mode: plan, default, accept-edits, auto, yolo or sudo. Claude Code's names work too (acceptEdits, bypassPermissions, dontAsk). alt+m cycles the five saved modes in the TUI. |
--yolo |
Same as --permission-mode yolo: no prompts; bash runs in the OS sandbox. |
--sudo, --dangerously-skip-permissions |
Session-only sudo: no prompts at all and bash without the OS sandbox. Deny rules, explicit ask rules, your organisation's policy, the hard-deny list and the secret-path guard still apply. Never saved; /sudo or alt+s toggles it. |
--sandbox |
Always run bash inside the OS sandbox (sandbox-exec on macOS, bubblewrap on Linux). |
--no-sandbox |
Never sandbox bash (yolo sandboxes it by default). |
--plan |
Start in plan mode: read-only, the plan goes to .venom/plans/. |
--approve, -a |
Trust this project's hooks, MCP servers and allow rules for this run only. |
--no-approve, -na |
Ignore this project's trust-gated configuration for this run, even when the project is trusted. |
--coordinator |
The main agent only reads and delegates: it gets no edit, write, patch or bash tools, and workers (task subagents) make the changes. |
--mode is pi's output mode (text, json, rpc), not a permission mode: venom --mode accept-edits stops with a hint to use --permission-mode.
What each mode allows:
| Mode |
Behaviour |
plan |
Read-only: reads, searches and read-only bash commands. |
default |
Reads in the workspace run; edits, writes and bash commands your rules don't allow ask first. |
accept-edits |
Edits in the workspace run; bash still asks unless a rule allows it. |
auto |
accept-edits, plus a classifier on the fast model decides what default would have asked (unlisted bash, MCP and app tools). Needs the OS sandbox, so it is not available on Windows. |
yolo |
Everything runs except hard denies, your deny and ask rules and protected paths. |
sudo |
No prompts, no sandbox (see above). Session-only. |
Without a terminal (print and JSON modes), an action that would ask is denied, and the model is told which allow rule would permit it.
Workspaces
| Flag |
What it does |
-w, --worktree [name] |
Run this session in a new git worktree, .venom/worktrees/<name> on branch venom/<name>. Without a name venom picks one (adjective-noun). The worktree is removed at exit when nothing in it would be lost. |
--from <ref> |
With -w: start the worktree from this ref instead of HEAD. |
--no-worktree |
Don't start in a worktree, even when workspaces.default says every session should. |
venom workspace manages these worktrees afterwards; see its reference page in this section.
| Flag |
What it does |
--edit-tool <choice> |
Which file-editing tool the model gets: auto (default: apply_patch for models trained on OpenAI's V4A patch format, edit for the rest), edit, apply_patch or both. apply_patch goes through the same permission checks, checkpoints, formatter and diagnostics as edit, and a patch applies atomically: a hunk that does not match writes nothing. |
--offline |
Offline mode: MCP servers are registered disabled and there is no web_fetch or web_search. Also stops pi's own startup network calls. |
--chrome |
Every browser tool from the start, in a Chrome window you can watch. |
--chrome-headless |
Every browser tool from the start, headless. |
--chrome-attach <port> |
Browser tools on a Chrome you started with --remote-debugging-port=<port> (its logins are in reach). |
--chrome-extension |
Browser tools on your own Chrome through the venom browser extension, one window per agent (pair it first with venom browser pair). |
--no-chrome |
No browser tools. |
Without a browser flag, and with Chrome, Chromium, Edge or Brave installed, the agent gets one browser tool, browser_navigate; the rest of the browser tools and a headless browser start on its first call.
Budgets, review and cost
| Flag |
What it does |
--output-budget <tokens> |
The output tokens this run is meant to use. When the model stops below 90% of it, a message tells it how much it used and to keep going. It stops nudging after three nudges once the last two continuations each produced under 500 tokens, and never nudges in plan mode, in a subagent or after a limit stop. Default: none (venom.yaml guards.output_budget). |
--no-self-review |
Skip the review of the branch's diff that runs before the agent opens a pull request with gh pr create (venom.yaml review.before_pr, on by default). |
--task <url|id> |
The pull request, issue or tracker key this session's spend counts toward (venom cost --by task). Default: the branch's. /task changes it in a session. |
Models and thinking
These are pi's flags; venom's provider resolves them against VENOM_BASE_URL.
| Flag |
What it does |
--model <pattern> |
The model: an exact id or a fuzzy match, provider/id, with an optional :<thinking> suffix. Beats VENOM_MODEL. Default venom-default. |
--provider <name> |
Look --model up in one provider only. venom never uses pi's built-in cloud providers unless you pick one this way or with /model. |
--api-key <key> |
A key for this run only. |
--thinking <level> |
off, minimal, low, medium, high, xhigh or max, clamped to what the model supports. |
--models <patterns> |
Comma-separated models (globs and fuzzy matches) that ctrl+p cycles through. |
--list-models [search] |
List the models the providers serve and exit. |
Sessions
| Flag |
What it does |
-c, --continue |
Continue the newest session of this directory. |
-r, --resume |
Pick a saved session to resume. |
--session <path|id> |
Open a session by file, id or id prefix. |
--session-id <id> |
Open the session with this exact id, creating it if it does not exist. |
--fork <path|id> |
Fork a saved session into a new one. |
--session-dir <dir> |
Where sessions are stored and looked up (beats VENOM_CODING_AGENT_SESSION_DIR). |
--no-session |
Don't save this session. |
-n, --name <name> |
The session's display name. |
--export <file> [out] |
Export a session file to HTML and exit. venom export writes the fuller trace. |
Output and process
| Flag |
What it does |
-p, --print |
Run the prompt, print the final answer, exit. |
--mode <text|json|rpc> |
The output interface: json writes every event as a JSON line, rpc reads commands on stdin. See Print, JSON and RPC modes. |
--tui-mode <mode> |
fullscreen (default) or regular (the transcript stays in the terminal's scrollback). |
--verbose |
The full startup header and resource lists (overrides quietStartup). |
-h, --help |
venom's help, then pi's. |
-v, --version |
Print the version and exit. |
Tools, resources and prompt (pi)
| Flag |
What it does |
-t, --tools <list> |
Comma-separated allowlist of tools (* patterns). A list of only +name/-name entries adds to or removes from the defaults. |
-xt, --exclude-tools <list> |
Tools to disable, MCP tools included. |
-nt, --no-tools |
Start with every tool disabled. |
-nbt, --no-builtin-tools |
Disable pi's built-in tools, keep extension tools. |
-e, --extension <path> |
Load an extension (repeatable). venom plugin dev <path> is the plugin author's shortcut. |
-ne, --no-extensions |
No discovered or configured extensions (explicit -e still loads). |
--no-mcp |
No MCP servers and no MCP tools for this run. |
--skill <path>, -ns, --no-skills |
Load a skill; or load none of the discovered ones. |
--prompt-template <path>, -np, --no-prompt-templates |
Load a prompt template; or none of the discovered ones. |
--theme <path>, --use-theme <name>, --no-themes |
Load a theme file, pick this run's theme, or load no themes. venom's own themes are chosen with ui.theme or /theme (see The terminal UI). |
-nc, --no-context-files |
Don't load AGENTS.md or CLAUDE.md. |
--system-prompt <text|file> |
Replace the system prompt. |
--append-system-prompt <text|file> |
Append to the system prompt (repeatable). |
| Input |
What it does |
message … |
The first prompt; several messages are sent one after another. |
@path |
Include a file or an image in the first prompt. |
| piped stdin |
Put before the prompt (print mode). - as the prompt means "the prompt is on stdin". |
Environment
The flags above override the environment. The variables venom --help lists:
| Variable |
What it sets |
Default |
VENOM_BASE_URL |
the OpenAI-compatible endpoint, including /v1 |
http://localhost:8787/v1 |
VENOM_API_KEY |
the key for it |
none |
VENOM_MODEL |
the model for every command (--model beats it) |
venom-default |
VENOM_FAST_MODEL, VENOM_SMART_MODEL |
the fast and smart delegation tiers |
venom-fast, venom-smart |
VENOM_CONTEXT_WINDOW |
a cap on the context window: the smaller of the server's window and this |
131072 when the server reports none |
VENOM_MAX_WIDTH |
the chat's width on wide terminals: columns, auto (100) or full |
auto |
VENOM_SOUND_PLAYER |
your own player command for event sounds |
afplay on macOS; pw-play, paplay or aplay on Linux; PowerShell on Windows |
VENOM_DEBUG |
1 prints harness diagnostics, hook messages and compaction steps |
off |
VENOM_ONLINE |
1 lets pi make its own startup network calls |
off |
VENOM_HOME |
venom's state directory |
~/.venom |
The complete list of venom.yaml keys and environment variables is in the venom.yaml reference and environment variables pages.
Errors
| Message |
Cause |
Invalid mode or a hint to use --permission-mode |
A permission mode was given to --mode. |
| A session flag conflict |
--fork cannot be combined with --session, --continue, --resume or --no-session; --session-id cannot be combined with --session, --continue or --resume. |
| A refusal naming the policy file |
Your organisation's policy forbids the flag (for example --sudo) or the VENOM_BASE_URL. |
auto mode is unavailable; running in … |
--permission-mode auto on a machine with no OS sandbox (Windows, or Linux without bubblewrap). There yolo also asks before bash commands, as accept-edits does. |