Skip to content
Docs menu

Flags

Every flag the venom command takes, venom's own and the ones it inherits from pi, with what each does and its default.

View .md

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.

Tools and editing

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

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.