---
title: Git, review and shipping commands
description: Find the commit that broke a test, try a goal several ways at once, track intents, sign and verify who made a change, revert it, and ship a branch or a stack of them.
section: cli
order: 120
audience: [user, operator, agent]
sources: [cli/src/bisect.ts, cli/src/try.ts, cli/src/intent.ts, cli/src/provenance.ts, cli/src/revert.ts, cli/src/ship.ts, cli/src/stack.ts, cli/src/evidence.ts, cli/src/capture.ts, docs/bisect.md, docs/try.md, docs/provenance.md]
features: [cli.bisect, cli.try, cli.intent, cli.provenance, cli.revert, cli.ship, cli.stack, cli.evidence, cli.capture]
---

These commands work on a git repository. None of them push, merge or open anything unless the command says so.

```bash
venom bisect "npm ci && npm test" --good v1.4.0 --explain
venom try "make the parser accept trailing commas" -n 3 --check "npm test"
venom provenance HEAD
venom ship --no-merge
```

## venom bisect {#bisect}

`venom bisect "<test-command>" [--good <ref>] [--bad <ref>] [--explain] [--model <id>] [--timeout <s>] [--json]` finds the commit that broke a test with `git bisect run`, in a throwaway worktree: your checkout is never touched. The test runs as `sh -c "<test-command>"` at each step: exit 0 is good, 125 skips the commit, anything else is bad.

| Option | Default | What it does |
|---|---|---|
| `--bad <ref>` | `HEAD` | A commit where the test fails. |
| `--good <ref>` | found | A commit where it passes. Without it, first-parent history is walked back (1, 2, 4 … 128 commits) until the test passes. |
| `--explain` | off | Ask the model (the session's, or `--model`) why the culprit broke the test: one request with its diff and the test output, secrets scrubbed. |
| `--timeout <s>` | `1800` | Give up after this long. |
| `--json` | off | `{ok, good, bad, steps, culprit, explanation, …}`. |

A fresh worktree has no dependencies: install them in the command (`"npm ci && npm test"`). Exit 0 when a culprit is found, 1 when not, 2 on usage.

## venom try {#try}

`venom try "<goal>" -n <N> [options]` runs the same goal as N attempts in N git worktrees at once, possibly on different gears, ranks them with a verifier and names the best. Nothing is merged: `venom workspace merge <name>` lands the winner (see [Workspaces](/docs/cli/workspaces.md)).

| Option | Default | What it does |
|---|---|---|
| `-n`, `--try <N>` | `3` | Attempts per round, 2–8. |
| `--check <cmd>` | none | The verifier, run in each worktree; exit 0 passes (`"npm test"`). |
| `--gears a,b,c` | the configured model | Gears to cycle through, one per attempt. |
| `--rounds <R>` | `1` | Rounds, 1–4; each round starts from the previous winner. |
| `--risk <tier>` | `low` | `low`, `medium` or `high`, as for `venom do`. |
| `--budget <usd>` | `1` | Spend cap per attempt. |
| `--model <id>`, `--cwd <dir>`, `--json` | | The model, the repository, JSON output. |

A passing check ranks first, then the smaller diff. Without `--check` the ranking is by diff size alone, which is weak evidence.

## venom intent {#intent}

The intent ledger: what is wanted, claimed by an agent, closed with evidence. Files live in `~/.venom/intents/`, offline. Ids may be shortened to a unique prefix.

| Command | What it does |
|---|---|
| `venom intent new <title> [--goal <text>] [--constraint <text>]… [--accept <check>]… [--parent <id>] [--risk-usd <n>]` | Record an intent with its acceptance checks. |
| `venom intent list [--status open\|claimed\|closed\|abandoned] [--parent <id>]` | List intents. |
| `venom intent show <id>` | One intent with its evidence. |
| `venom intent claim <id> [--by <name>]` | Claim it (default: `$VENOM_AGENT`, else you). |
| `venom intent evidence <id> <text> [--kind <kind>] [--ref <ref>]` | Attach evidence. |
| `venom intent close <id> [--evidence <text>] [--abandon]` | Close it; needs evidence (or `--abandon`), refused while sub-intents are open. |

All take `--json`.

## venom provenance {#provenance}

Signed receipts for code changes: who made a commit and why.

| Command | What it does |
|---|---|
| `venom provenance <sha> [--trust <key id>…] [--depth <n>] [--json]` | Verify a commit's receipt (signature, tree and parents, the `Venom-Receipt` trailer, the links to earlier receipts) and print who made the change: agent, models, tools, permission decisions and human approvals. Exit 0 when it verifies and its signer is trusted (this machine's key, or `--trust`), 1 otherwise. |
| `venom provenance record [--session <id\|latest>] [--intent <id>] [--no-amend]` | Sign a receipt for `HEAD` from a saved session, add the `Venom-Receipt` trailer to its message (amends `HEAD`; `--no-amend` leaves it, so the commit won't verify) and store the receipt in `refs/notes/venom-provenance`. `--intent` (default `$VENOM_INTENT`) names the intent it was made for. |
| `venom provenance key` | The key id of this machine's signing key (`~/.venom/provenance.key`, made on first use). |

Share receipts with `git push origin refs/notes/venom-provenance`.

## venom revert {#revert}

| Command | What it does |
|---|---|
| `venom revert <intent> [--rev <rev>] [--include <sha>…] [--json]` | List the commits whose verified receipt names the intent, the later commits that touch the same files (shown first: they may depend on it), the order of the reverts, and whether they apply cleanly (tried in a throwaway worktree). |
| `venom revert <intent> --apply [--dir <path>] [--test <cmd>]` | Make branch `venom-revert/<intent>` in a new worktree, revert the commits there newest first, and run `--test` in it. Nothing is pushed or merged. |

`--include` adds commits whose receipt was lost (a squash merge). Exit 0 when the reverts apply (and `--test` passes), 1 on a conflict, a failing test or no match, 2 on usage.

## venom evidence {#evidence}

`venom evidence [--base <ref>] [--json | --markdown] [--extra <file.json>] [--coverage <file>]… [--post <pr>]` prints the evidence bundle for the current change: changed files, tests added, the impacted-test selection, diff invariants, and whatever `--extra` supplies (test runs, bench and eval deltas, session, screenshots, risk). Nothing runs and no model is called. `--base` defaults to `HEAD` (uncommitted changes; use `main` for a branch). `--coverage` takes a Go cover profile or lcov file and lists the added lines no test reaches. `--post <pr>` posts the markdown as one comment with `gh`.

## venom ship {#ship}

`venom ship [--base <ref>] [--title <title>] [--no-merge]` ships the current branch: the gate plan, the evidence bundle, a pull request, and the merge queue. `--base` defaults to `origin/main`, `--title` to the branch's last commit subject; `--no-merge` opens the pull request and posts the evidence without queueing it. Run it from a feature branch with a clean tree. The outcome is merged, needs-human, or failed with the stage. `/ship` does the same in a session.

## venom stack {#stack}

`venom stack <status|submit|restack|land|split> [--base <ref>] [--dry-run]` manages stacked pull requests: the branches between the trunk and `HEAD`, each on the one below.

| Subcommand | What it does |
|---|---|
| `status` | The stack, bottom first, with each branch's pull request. |
| `submit` | Push every branch and open (or retarget) its pull request on the branch below. |
| `restack` | Rebase every branch onto the one below. |
| `land` | Land the stack bottom up through the gate, one pull request at a time. |
| `split` | Cut this branch into a stack of small ones, dependencies first: `--max-lines N` (default 400), `--name <n>`, `--check <cmd>` run on every layer. |

`--base` is the trunk (default `origin/main`); `--dry-run` prints the order or plan for `land` and `split`.

## venom capture {#capture}

```bash
venom capture run --snapshot ./out --out before -- ./build.sh
venom capture diff before after
```

`venom capture run [--snapshot <dir>]… [--out <dir>] [--input <text>]… [--timeout <s>] [--cols N --rows N] -- <cmd…>` records a command under a pseudo-terminal: a journal of input, output and exit, the rendered terminal frames, and before and after snapshots of the `--snapshot` directories. `venom capture diff <a> <b>` compares two recordings (for instance before and after a refactor): output, final screen and file effects, ignoring timestamps. It exits 1 when they differ. Offline; secrets are redacted. Defaults: `--out ./venom-capture-<time>`, `--timeout 60`, 80x24.

## Troubleshooting {#troubleshooting}

| Symptom | Cause and fix |
|---|---|
| `venom bisect` finds no culprit | The test passes at `--bad`, fails at `--good`, or every candidate was skipped (exit 125). |
| `venom provenance` exits 1 on your own commit | It was amended or rebased after `record`, or recorded with `--no-amend`. |
| `venom revert` matches nothing | The commits' receipts were lost in a squash merge: add them with `--include`. |
| `venom ship` or `venom stack` refuses | Both need a clean tree; `ship` runs from a feature branch, `stack` from the top branch of the stack. |
