---
title: Cost, health and routing commands
description: The venom subcommands that check the setup and explain spend, routing, tool errors, wasted tokens, flaky tests and local models.
section: cli
order: 100
audience: [user, operator, agent]
sources: [cli/src/doctor.ts, cli/src/cost.ts, cli/src/usage.ts, cli/src/explain-cost.ts, cli/src/diet.ts, cli/src/tool-stats.ts, cli/src/forecast.ts, cli/src/routes.ts, cli/src/flaky.ts, cli/src/models.ts]
features: [cli.doctor, cli.cost, cli.diet, cli.stats, cli.forecast, cli.routes, cli.flaky, cli.models]
---

These commands run outside a session and print a report; most have a slash command that shows the same inside one. All take `--json` for one machine-readable object (see [Print, JSON and RPC modes](/docs/cli/headless.md#subcommand-json)).

```bash
venom doctor                 # is the setup right?
venom cost week --by model   # what did I spend, on what?
venom explain-cost latest    # why did that session cost so much?
venom routes --window 1h     # where did my requests go?
venom diet                   # where do my sessions waste tokens?
```

## venom doctor {#doctor}

Checks the environment, the endpoint and key, the models and their context windows, the OS sandbox, what the current project loads and where your prompts go. Each line is PASS, WARN or FAIL with a fix. Exit 1 when a required check fails.

| Option | What it does |
|---|---|
| `--only <sections>` | Run only these sections (comma-separated): `policy`, `environment`, `cloud`, `orchestrator`, `probe`, `browser`, `sandbox`, `project`, `sovereignty`. Only their required checks set the exit code. |
| `--probe` | Also send the default model two tiny requests: a chat (time to first token) and a structured tool call. Costs a request. |
| `--model <id>` | The model to probe (default `VENOM_MODEL`, then `settings.json`'s `defaultModel`, then `venom-default`). |
| `--fix` | After the report, offer a fix for each check venom can repair, asking before each; prints the steps it can't take. |
| `--yes`, `-y` | With `--fix`: apply every fix without asking. |
| `--check-update` | Also read the latest release's version from GitHub (one small request; off by default). |
| `--json` | Machine-readable output. |

## venom cost {#cost}

```bash
venom cost                     # today, last 7 days, this month, then this month in detail
venom cost week --by gear
venom cost --task owner/repo#123
```

`venom cost [today|week|month|<n>d|YYYY-MM-DD] [--by <dim>] [--task <ref>] [--json]` shows your spend today, over the last 7 days and this month, then the window (default this month) by gear, model (requested and served), role, task and the costliest sessions, with what the prompt cache saved and the partial responses (the client went away). Days are UTC.

| Option | What it does |
|---|---|
| `--by <dim>` | One breakdown: `gear`, `model`, `role`, `day`, `session`, `project` (the budget envelope's tag, `x-venom-project` or `VENOM_PROJECT`), `task` (the pull request, issue or tracker key: `venom --task`, the branch, the pull request venom opened) or `outcome` ($ per merged pull request, closed issue and passing test run, from GitHub through `gh`). |
| `--task <ref>` | Only one task: a pull request or issue URL, `owner/repo#123`, `ENG-142`. |
| `--since <t>` | The window: `today`, `week`, `month`, `30d` or a UTC day. |
| `--json` | One object, `{"type":"cost",…}`. |

The rows come from Venom Cloud (`GET /v1/usage/summary` for `VENOM_API_KEY`) when `VENOM_BASE_URL` is a cloud; with the Go orchestrator or offline, from this machine's saved sessions at the bundled list prices, with the orchestrator's own totals beside them when it answers. In a session, `/cost` is this session's tokens and cost and `/cost today|week|month [--by …]` the same view as the command.

## venom usage {#usage}

`venom usage [--json] [--session <id>]`: spend and budgets for your key at `VENOM_BASE_URL`: today, the last 7 days and this month by model, the key's daily and monthly budgets with their reset times, today's costliest sessions, and one session with `--session` (its subagents rolled in). `/usage` shows the same for the running session.

## venom explain-cost {#explain-cost}

`venom explain-cost [session] [--json] [--offline]`: why a session cost what it did, turn by turn: where the money went (main agent, subagents, summaries, side requests), the costliest turns, prompt-cache churn and its causes, tool outputs that weighed on later requests, reasoning tokens, the exploration the repo map saved, and tips with the numbers behind them. Priced at list price from the session's records; the orchestrator's figure is added when it answers (`GET /v1/usage`), unless `--offline`. `session` is an id, a prefix or `latest` (default: the newest in this directory). `/explain-cost` explains the session you are in.

## venom diet {#diet}

`venom diet [--session <id|latest>] [--all] [--days <n>] [--json]`: the biggest sources of avoidable tokens in this repository's saved sessions, each with a fix: files read again unchanged, large tool outputs re-sent on later requests, prompt-cache churn, a heavy start (system prompt, skills, MCP tool lists) and context left to grow past 150k tokens. `--session` looks at one session, `--all` at every directory, `--days` sets the window (default 7). Nothing leaves the machine.

## venom stats tools {#stats}

`venom stats tools [--days <n>] [--model <m>] [--all] [--json]`: per model and tool, from this repository's saved sessions: calls, error rate, the most common error kinds and p50/p95 output tokens. `edit` and `apply_patch` failures are split into no match, multiple matches and stale read. `--days` (default 7), `--model` (models whose name contains it), `--all` (every directory). Offline.

## venom forecast {#forecast}

`venom forecast "<task>" [--gear <name>] [--since 90d] [--json]`: what a task will likely take on each gear, in tokens and dollars (p50 and p90), from the most similar tasks in your saved sessions. A gear with enough sessions of its own is measured on them; otherwise the similar tasks' sizes are priced at the gear's model. `--gear` limits it to one gear, `--since` sets the history (default 90 days). Nothing is sent to a model. `venom do --forecast` prints the same for a background run.

## venom routes {#routes}

`venom routes [--window 1h|24h|7d] [--alias <a,b>] [--json]`: where the orchestrator sent your requests, and why: per alias, its targets in order with their live state (ok, cooling down, circuit open, disabled), the share each served, p50 latency and time to first token, fallbacks by reason, and the latest fallbacks. `--window` takes any duration up to 31 days (default `24h`); `--json` prints the orchestrator's `GET /v1/routing` answer. `/routes [window] [alias]` shows the same in a session.

## venom flaky {#flaky}

| Command | What it does |
|---|---|
| `venom flaky [list] [--all] [--json]` | This repository's flaky tests, most flaky first (`--all`: every repository). |
| `venom flaky issue <n\|text> [--yes]` | Show the issue it would file, ask, then run `gh issue create`. |
| `venom flaky dismiss <n\|text>` | Stop proposing an issue for it. |
| `venom flaky clear [<n\|text>]` | Forget one test, or all of this repository's. |

A flaky test is one that failed and then passed on a rerun with no code change, seen while venom ran tests in your sessions. The record is local (`~/.venom/flaky/`). After `tests.flaky_after` occurrences (default 3) venom proposes an issue; it never files one itself.

## venom models {#models}

This machine's local models, through the orchestrator's admin API (`VENOM_ORCH_URL`, default `http://127.0.0.1:8787`, with `VENOM_ADMIN_TOKEN`).

| Command | What it does |
|---|---|
| `venom models [status]` | Hardware, backends, which model serves `venom-default` and `venom-fast`, strain, pulls in progress. |
| `venom models list [--all]` | Models for this machine: fit, memory, tokens/s, tool support, installed. `--all` adds ones too big for it and vLLM models. |
| `venom models pull <tag> [--use default\|fast]` | Download an Ollama model (`qwen3:14b`, `hf.co/<repo>:<quant>`) with a progress bar. |
| `venom models use <tag> [--fast]` | Serve `venom-default` (or `venom-fast` with `--fast`) with it; pulls it first when needed. |
| `venom models setup` | The recommended default and fast models for this machine, pulled and selected. |
| `venom models rm <tag>`, `venom models unload <tag>` | Delete a model from Ollama; free the VRAM a loaded model holds. |
| `venom models gears [--window 7d]` | Per gear, what its main model measured on your requests: p50 latency, error rate, $/request. |
| `venom models local suggest [--days 7] [--gpu-usd-per-hour X]` | Which cloud requests of the side roles a local model could serve, with the weekly saving. |

`ctrl+c` during a pull stops watching; the pull goes on in the orchestrator.

## Troubleshooting {#troubleshooting}

| Symptom | Cause and fix |
|---|---|
| `venom doctor` FAILs on the endpoint | `VENOM_BASE_URL` must include `/v1` and be reachable; run with `--only orchestrator` to see just that. |
| `venom cost` shows "local" figures | The endpoint is not a Venom Cloud, or it didn't answer; the figures are estimates at list price. |
| `venom routes` or `venom models` gets 401 | Your key or `VENOM_ADMIN_TOKEN` doesn't match the orchestrator's. |
| `venom flaky issue` fails | `gh` isn't installed or signed in. |
