---
title: Project setup, memory and onboarding commands
description: Set a project up for venom, keep its memory, index its code, and help new people learn a codebase with tours, explanations and answers that cite their sources.
section: cli
order: 110
audience: [user, operator, agent]
sources: [cli/src/init.ts, cli/src/explain.ts, cli/src/tour.ts, cli/src/ask.ts, cli/src/onboard.ts, cli/src/memory-cli.ts, cli/src/index-command.ts, cli/src/lessons.ts, packages/harness/src/extensions/automemory.ts, docs/explain.md, docs/tour.md]
features: [cli.init, cli.explain, cli.tour, cli.ask, cli.onboard, cli.memory, cli.index, cli.lessons]
---

```bash
venom init                       # AGENTS.md and starter permission rules for this project
venom explain src/billing        # an onboarding tour of one module
venom tour --dry-run             # plan and cost of an architecture tour
venom ask "how do refunds work?" # an answer with its sources
venom memory                     # what venom remembers about this project
```

## venom init {#init}

`venom init [--yes] [--dry-run] [--no-permissions] [--model <id>] [instructions…]` analyses the project (read-only) and writes a short `AGENTS.md`: commands, layout, gotchas. An existing `AGENTS.md` is refined; a project with only `CLAUDE.md` gets that refined. It also proposes `.venom/permissions.json` allow rules for the test, build and lint commands it found, and `.gitignore` entries for venom's local state.

| Option | What it does |
|---|---|
| `--yes`, `-y` | Accept the proposals without asking. An existing memory file is not overwritten: the proposal goes to `<name>.venom-proposed`. |
| `--dry-run`, `-n` | Print what would be written; write nothing. |
| `--no-permissions` | Don't propose `.venom/permissions.json`. |
| `--model <id>` | The model for the analysis (default `VENOM_MODEL`, then `venom-default`). |
| `instructions…` | Extra guidance, for example `"focus on the API package"`. |

In a terminal each file's diff is shown and you choose; without one, nothing is written unless `--yes`. `/init` in a session does the same.

## venom explain {#explain}

`venom explain <path> [--refresh] [--model <id>] [--json]` writes an onboarding tour of one module: what it is for, its entry points, key types, how data flows through it, where its tests are, and the gotchas. A read-only agent writes it (it reads files, never edits). The result is cached in `~/.venom/explain` until a tracked file under `<path>` changes; `--refresh` writes a new one anyway. `--json` prints `{ok, path, hash, cached, model, createdAt, files, text}`.

## venom tour {#tour}

`venom tour [path] [--out <file> | --print] [--gear <name> | --model <id>] [--max-usd <n>] [--exclude <dir>] [--dry-run] [--full] [--json]` writes an architecture tour for new joiners from the repo map and the repository's docs: components, entry points, data flow, how to run and test, key files, with mermaid diagrams. It goes to `docs/TOUR.md` (or `<path>/TOUR.md`) and is regenerated incrementally: only the parts whose facts changed go back to the model.

| Option | Default | What it does |
|---|---|---|
| `path` | the whole repository | A directory to tour. |
| `--out <file>` | `docs/TOUR.md` | Write here instead. |
| `--print` | off | Print the tour; write nothing. |
| `--gear <name>` | `normal` | The gear whose smart tier writes the prose. |
| `--model <id>` | none | A model instead of a gear's. |
| `--max-usd <n>` | `0.5` | Stop before a request that would pass this spend. A local model with no list price costs nothing. |
| `--dry-run` | off | The plan and the cost estimate; nothing is sent or written. |
| `--full` | off | Regenerate every part. |
| `--exclude <dir>` | none | Leave a directory out (repeatable); fixtures, vendor, dist and node_modules always are. |
| `--json` | off | Machine-readable result. |

The facts are gathered locally with no model, and the text sent to the model is secret-scrubbed. Exit 0 on a tour, 1 when nothing could be toured or the cap stopped it early, 2 on usage.

## venom ask {#ask}

`venom ask "<question>" [--cloud-only | --local-only] [--gear <name>] [--json]` answers a question from what your team knows, with the sources cited: your organisation's memory, team library and the session summaries you may open on Venom Cloud (needs `venom cloud login`), and the markdown docs of this checkout (README, `docs/`, `docs/TOUR.md`).

| Option | What it does |
|---|---|
| `--cloud-only` | Send no passages from this checkout. |
| `--local-only` | Call nothing: print the best matching passages of this checkout. |
| `--gear <name>` | Answer with this gear's summary model (default: your organisation's default gear). |
| `--json` | Print the answer as JSON. |

The answer comes from the summary model, so it is cheap, and a question nothing matches costs nothing. The same works in Slack (`/venom ask`) and on the console's Ask page.

## venom onboard {#onboard}

| Command | What it does |
|---|---|
| `venom onboard [list] [--path <name>] [--json]` | Your organisation's first tasks for new members, and where you are. |
| `venom onboard next [--path <name>]` | Start the next step. |
| `venom onboard done <step>`, `venom onboard undo <step>` | Mark a step you do by hand (reading the tour) done, or take it back. |

The steps run on your own repositories (read the tour, run the tests, fix a good first issue, ship a small PR) and tick themselves when the work shows up: a finished session, a session that changed files, a merged pull request. Pull request and issue steps need `tasks.lookup: gh` in venom.yaml. `--path` picks one of your organisation's onboarding paths. Needs `venom cloud login`.

## Memory {#memory}

venom keeps a project's auto-memory: a `MEMORY.md` index of typed memory files, loaded into each session's prompt, which the agent reads and writes with its `memory` tool (actions `list`, `read`, `save`, `update`, `delete`, `verify`, `prune`, `sync`, `propose`; scopes `me`, `team`, `org`). Claude Code's memory for the same project is read too.

| Command | What it does |
|---|---|
| `venom memory [list]` | This project's memories: venom's, then Claude Code's (read-only). |
| `venom memory show <name>` | One memory file. |
| `venom memory edit <name>` | Open it in `$EDITOR` (a Claude Code memory is copied to venom's directory first). |
| `venom memory rm <name> [--yes]` | Delete one of venom's memories. |
| `venom memory path` | Where the memory files are. |
| `venom memory sync [--base <ref>] [--apply] [--commit] [--pr <n>] [--check] [--json]` | Which `AGENTS.md`/`CLAUDE.md` updates the branch's change needs. `--apply` makes the edits with the model, `--commit` commits them, `--pr <n>` puts a "Memory updates" section in that pull request, `--check` exits 1 while an update is pending. |
| `venom memory org [refresh] [--json]` | Your organisation's approved facts from Venom Cloud. |
| `venom memory propose "<fact>" [--team \| --repo]` | Propose a fact to your organisation; an admin approves it in the console. `--team` scopes it to your key's key group, `--repo` to this repository. |

In a session: `/memory [show|edit|forget|path] <name>`, `/memory org`, `/memory propose <fact>`, and `/memory-sync`.

| Key | Default | What it does |
|---|---|---|
| `memory.auto` | `on` | `off`: no index in the prompt, no `memory` tool, no `/memory`. |
| `memory.dir` | `~/.venom/projects/<slug>/memory` | Where the memory files go (absolute, `~/…` or relative to the project root). From a project file it needs the project to be trusted. |
| `memory.max_index_lines` | `200` | Index lines loaded into the prompt (at most 12 KiB either way). |
| `memory.org_dir` | none | A shared directory of organisation-wide memory every machine reads. Team memory needs no setting: it is `<project>/.venom/memory`, committed to git. |

## venom index {#index}

`venom index [--status | --query <text> [--limit <n>]] [--json]` manages the semantic code index of this git work tree (`.venom/index/`), which the agent's `code_search` uses in its `semantic` mode. With no flags it brings the index up to date (only changed files are re-read and only new chunks embedded); `--status` shows what is stored and the embedding model; `--query` prints the nearest chunks (`--limit`, default 10). Embeddings come from the orchestrator's `venom-embed` route, and only when every target of that route is local; without it the command says so and exits 1, and the agent searches with grep.

## venom lessons {#lessons}

| Command | What it does |
|---|---|
| `venom lessons [list] [--all] [--json]` | The lessons this project learned from closed tasks, best supported first (`--all`: rejected ones too). |
| `venom lessons show <id>` | One lesson with its evidence. |
| `venom lessons reject <id>` | Keep it out of the prompt from the next session. |

Each lesson has a cue, an action and the evidence behind it. Lessons load into the system prompt at the next session start as guidance, never as a permission. The record is local: `.venom/lessons.json`.

## Troubleshooting {#troubleshooting}

| Symptom | Cause and fix |
|---|---|
| `venom init` wrote nothing | No terminal to choose in: add `--yes`, or `--dry-run` to see the proposal. |
| `venom tour` stops early | `--max-usd` was reached; raise it, or `--dry-run` for the estimate. |
| `venom ask` uses only local docs | Not signed in to Venom Cloud (`venom cloud login`). |
| `venom index` exits 1 | The orchestrator has no all-local `venom-embed` route. |
