---
title: Flags
description: Every flag the venom command takes, venom's own and the ones it inherits from pi, with what each does and its default.
section: cli
order: 10
audience: [user, operator, agent]
sources: [cli/src/branding.ts, cli/src/setup.ts, cli/src/workspace.ts, packages/harness/src/extensions/permissions.ts, packages/harness/src/extensions/patch.ts, packages/harness/src/extensions/output-budget.ts, packages/harness/src/extensions/selfreview.ts, packages/harness/src/extensions/task.ts, packages/harness/src/permissions/modes.ts]
features: [cli.options, cli.output-budget, cli.patch, cli.selfreview]
---

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.

```bash
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 {#permissions}

| 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](/docs/cli/plan-mode.md): 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 {#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 {#tools}

| 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 {#budgets}

| 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 {#models}

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 {#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 {#output}

| 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](/docs/cli/headless.md). |
| `--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) {#resources}

| 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](/docs/cli/tui.md#themes)). |
| `-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}

| 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 {#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](/docs/configuration/venom-yaml.md) and [environment variables](/docs/configuration/env-vars.md) pages.

## Errors {#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. |
