Skip to content
Docs menu

venom CLI quickstart

Install the venom CLI, point it at a model, run a first session and check the setup with venom doctor.

View .md

From nothing to a first session in a few minutes. The CLI page has the downloads.

Install

On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh | sh

The script picks the build for your OS and chip, downloads it and SHA256SUMS from the public releases repository, checks the hash, unpacks it and links ~/.venom/bin/venom. If ~/.venom/bin is not on your PATH it prints the line to add. Each build includes its own Node runtime, so nothing else is needed.

To install by hand, download the archive for your platform, check it with shasum -a 256 -c SHA256SUMS --ignore-missing, unpack it anywhere and run bin/venom. Install venom covers the installer's options, Windows, updates, uninstalling and building from source.

venom --version

Pick a model

venom speaks the OpenAI API. VENOM_BASE_URL says where to send requests, VENOM_API_KEY is the key for that endpoint (if it needs one) and VENOM_MODEL picks the model. Put the exports in your shell profile to keep them.

Offline, with Ollama on your machine:

ollama pull qwen3:8b
export VENOM_BASE_URL=http://localhost:11434/v1
export VENOM_MODEL=qwen3:8b

With Venom Cloud, using a vck_ key from the console (cloud quickstart has the steps):

export VENOM_BASE_URL=https://cloud.usevenom.dev/v1
export VENOM_API_KEY=vck_…

Any other OpenAI-compatible endpoint (vLLM, SGLang, llama.cpp, a gateway or a provider) works the same way: its base URL including /v1, its key and a model it serves.

Variable What it sets Default
VENOM_BASE_URL The OpenAI-compatible endpoint, including /v1 http://localhost:8787/v1 (a local orchestrator)
VENOM_API_KEY The key for that endpoint none (no Authorization header)
VENOM_MODEL The model to use venom-default (the orchestrator's default alias)

Local or cloud models compares the options (Ollama, the desktop daemon, your own orchestrator, Venom Cloud, a provider) and shows how to save the endpoint in ~/.venom/config.yaml instead of exporting it.

A first session

Start venom in your project:

cd ~/work/app
venom                          # the interactive agent
venom -p "explain this repo"   # one prompt, printed answer
venom -c                       # continue the last session here

venom init proposes an AGENTS.md and starter permission rules for the project. If the project is set up for Claude Code, venom reads its CLAUDE.md, skills, commands, agents, settings and .mcp.json as they are. Hooks, MCP servers and allow rules from a project take effect only once you trust it; venom asks the first time.

What the first run looks like

  1. Trust. In a project that ships configuration that can run code or loosen permissions (hooks, MCP servers, allow rules, plugins), venom lists what would run and asks: Trust this project, Trust parent folder, Don't trust (ignore it), or Decide later. Until you trust it, venom ignores those items and runs with your own settings only. venom trust asks the same question from a shell (venom trust --yes without a terminal), venom trust --list shows your decisions and venom trust --revoke undoes one. --approve trusts a project for one run.

  2. The prompt. Type a request and press Enter. The agent reads files, runs commands and edits; anything your mode and rules don't allow asks you first. Esc stops the current turn.

  3. The status bar at the bottom shows the directory and git branch, then the permission mode and sandbox, the context window used, running subagents, the session's cost and tokens, and the model with its thinking level:

    ~/work/app ⎇ main
    ⏵ edits sbx  ctx 42%  2 agents 1 wait  $0.012  12k↑ 3.1k↓ 50k⚡        gpt-5.4-mini high

Useful from the start: ctrl+g ? lists every key binding, typing / lists the slash commands, /model switches models, /undo takes back the last file change, and /context and /cost show what the session holds and has spent. To switch between cheap and strong models in one keystroke, see Your first gear.

Permission modes

Switch with alt+m or /mode. Rules apply as deny, then ask, then allow. Shell commands are parsed, and each part of a compound command is judged on its own. A short list of destructive commands (such as rm -rf ~ or piping curl into a shell) is denied in every mode.

Mode What it allows
plan Read-only. The agent explores and proposes a plan; no file changes, no commands that write.
default Edits and commands your rules don't allow ask you first.
accept-edits Edits in the workspace go ahead; commands still ask.
yolo Runs without asking. Bash runs inside the OS sandbox on macOS and Linux: writes stay in the workspace and temp dirs, network through an allowlist.

Your own rules live in ~/.venom/permissions.json; settings in ~/.venom/config.yaml, or a venom.yaml in the project.

Check the setup

venom doctor

It checks the endpoint (reachable, your key, the models and their context windows), the OS sandbox, what the current project loads and where your prompts go, and prints PASS, WARN or FAIL with a fix on each line. venom doctor --probe also sends the model a short chat and a tool call. Troubleshooting lists every flag and the common failures.

Update

Run the install line again; it installs the newest release next to the old one and moves the link. Set VENOM_VERSION to install a specific version.

Windows (beta)

In PowerShell:

irm https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.ps1 | iex

It installs to %USERPROFILE%\.venom\bin and adds that to your user PATH. Windows has no OS sandbox, and venom says so when it starts: in yolo, commands your rules don't allow still ask, and auto mode is unavailable. For the full sandbox, run the Linux build in WSL.

Next steps