# CLI reference

> Every weave command grouped by task, with flags, JSON output and environment variables.
>
> Source: https://www.weave.directory/docs/cli

Every `weave` command, grouped by task. `weave --help` and `weave <command> --help` print the same information. This page describes CLI **0.4.0**.

Commands marked *(connected)* need a checkout connected to the hosted service. Everything else also works in local mode (`weave init --local`), where workstreams live in `.weave/` on your device and you own every symbol.

## Install

```bash
curl -fsSL https://weave-cli.com/install.sh | sh          # macOS, Linux (installs weave and weave-watcher)
irm https://weave-cli.com/install.ps1 | iex                 # Windows PowerShell
weave --version
```

The installer puts the binaries in `~/.local/bin` (`WEAVE_INSTALL_DIR`); `WEAVE_VERSION` picks a version. More options: [weave-cli.com/docs/install](https://weave-cli.com/docs/install).

## Global options

| Option | Meaning |
| --- | --- |
| `--agent <NAME>` | Act as this AI agent (sets `WEAVE_AGENT`): its own session, active workstream and draft on this device. |
| `--agent-model <MODEL>` | The agent's model (sets `WEAVE_AGENT_MODEL`). |
| `--json` | Print one JSON document on stdout instead of text. |
| `-V, --version` / `-h, --help` | Version / help. |

Options work before or after the subcommand.

## JSON output

With `--json`, stdout carries exactly one JSON document; text goes to stderr.

- **Success:** the command's fields plus `warnings: [{code, message, paths}]`, exit status 0.
- **Failure:** `{"error": {"code", "message", "retryable", "error_id"?, …}, "warnings": […]}`, exit status 1.
- Error and warning codes: [For AI agents](https://www.weave.directory/docs/agents#json-one-document-per-command).
- Commands without JSON output refuse `--json` with `unsupported` and do nothing: `login`, `config`, `remote`, `ignore`, `kinds`, `enrichment-prompt`, `install-claude`, `migrate`, `watcher`, `mcp`, `heatmap`, foreground `serve`, `index`, `enrich`, `thread`, `symbols`, `start`, `checkout --sparse`.

| Command | Document |
| --- | --- |
| `init` | `{root, mode, created_weaveignore}`; with `--server` also `server, user, workstream, head, weaves, files` |
| `clone` | `{repo, dir, workstream, head, files, bytes, server, state_included}` |
| `status` | `{workstream, head, mode, parent, settings, you, unread_messages, draft, awaiting, unadded, held, resolution_points, change_requests, suggestions_to_review, my_suggestions, signature_notices, …}` |
| `status --symbols` | `{session, workstream, base_head?, symbols: [{action, target, kind, signature?, old_signature?, detail?}], awaiting?}` |
| `add` | `{workstream, added, left_out, routed}` |
| `stitch` | `{result: weaved\|suggested\|resolved\|awaiting, workstream, stitch, sealed, head, base, at, duplicate, suggestions, routed, change_requests, inherited, files: {written, removed, carried, held}, held_back, rest_drafted, …}` |
| `stitch --paths` | adds `added`, `released` |
| `stitch --sessions` | `{sessions: [{session, intent, ok, result \| error}]}` |
| `sync` | `{workstream, head, arrived, already, written, removed, carried, held: [{path, target, since}], routed, updates}` |
| `drafts` | `{session, drafts: [{session, mine, workstream, paths, symbols, updated_at, age_secs, base_head, behind, awaiting, change_requests}]}` |
| `claim` | `{claimed, conflicts: [{target, owner, held}], missing, lease_secs}` |
| `owners` | `{workstream, fetched_at, from_cache, stale?, me, entries: [{target, path, symbol?, owned, owner, part?, feature, live, expires_in_secs, mine, via, scope}]}` |
| `outline` | `{workstream, exports_only, files: [{path, owner?, disk?, symbols: [{name, kind, signature, exported, owner?, children?}]}], files_without_symbols, truncated?}` |
| `context` | `{target, file, symbol, kind, line, exported, signature, doc?, owner?, in_drafts, callers, callees, decisions, last_stitch?, …}` |
| `find` | `{query, total, hits: [{target, file, symbol, kind, line, signature, doc?, exported, score, matched}]}` |
| `search` | `{query, workstream, semantic, head?, stale?, indexing?, total, hits, budget_tokens, truncated, notes?}` |
| `notices` | `{session, workstream, baseline, cursor, notices: [{kind, target, old_signature?, new_signature?, drafts, affects}], server_notices, …}` |
| `resolutions` / `resolutions show` / `resolve` | `{workstream, resolution_points}` / the point / `{resolution_point, changeset, files_written, weaved, files}` |
| `workstream new` / `list` / `remove` / `restore` | `{created, parent, head, settings, switched, files}` / `{active, workstreams: [...]}` / `{removed, unpromoted, closed_change_requests, closed_suggestions, released_claims}` / `{restored, parent, head}` |
| `promote` / `refresh` / `integrate` | `{to, stitch, dependencies, results: [{result: weaved\|already_present\|waiting\|rejected}]}` / `{workstream, from, applied, change_requests, pending}` / `{workstream, group, origin, applied, change_requests, open}` |
| `log` / `timeline` | `{verified, entries: [{id, at, actor, agent, action, description}]}` / `{workstream, head, items: [{changeset, at, author, agent, intent, why, origin, promoted_to}], more}` |
| `seed` | `{result, workstream, from, from_repo, state, head, files_seeded, suggestions, left_out: [{path, reason}], files}` |
| `msg inbox` / `msg wait` | `{unread, messages}` / the message, or `{messages: [], timed_out: true}` (exit 2) |
| `serve --status` | `{running, pid, build, version, root, socket, started_at, uptime_secs, idle_secs, running_commands, commands_served, server_connections, watch}` |

## Setup

| Command | Does |
| --- | --- |
| `weave login [--url <URL>]` | Ask for a personal access token (hidden input, or stdin: `echo $TOKEN \| weave login`), verify it with the platform and save it in `~/.weave/config.json` (mode 0600). |
| `weave clone <ORG/REPO> [DIR] [-w, --workstream <WS>] [--server <URL>]` | A working checkout in one download: every file of the workstream head (default `main`), verified, with `.weave/` connected. `DIR` defaults to the repository name and must be new or empty. *(connected)* |
| `weave init [--local \| --server <URL>]` | Create `.weave/` in this folder. `--server` connects it (existing files are never overwritten); `--local` keeps workstreams on this device. Without either in a terminal, a wizard asks and offers to wire AI tools (Claude Code, Gemini CLI, Cursor, Codex). Writes a starter `.weaveignore`. |
| `weave config <KEY> <VALUE>` | Set a key in `~/.weave/config.json` (`platform_url`, `server_url`, `skip_wired_platforms`). |
| `weave remote add <NAME> <URL>` / `weave remote list` | Record repository URLs; `origin` (or the only one) names the repository (`org/name`). |
| `weave ignore [list]` / `add <PATTERN>` / `remove <PATTERN>` | Built-in ignores and `.weaveignore` (supports `!` exceptions, `/` anchors, trailing `/` for folders). |
| `weave kinds list` / `add <NAME>` / `remove <NAME>` | Stitch kinds (defaults `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `change`). |
| `weave migrate` | Upgrade a legacy `.weave/` (also runs automatically). |
| `weave install-claude` | Add a Weave pointer to `./CLAUDE.md`. Then `claude mcp add weave -- weave mcp`. |
| `weave serve [--detach] [--idle-timeout <SECS>] [--watch \| --no-watch] [--socket <PATH>]` | One fast background process per checkout ([details](https://www.weave.directory/docs/agents#weave-serve-one-fast-process-per-checkout)). Unix only. |
| `weave serve --status` / `--stop` | Is one running here (exit 1 when none) / stop it. |

## Drafts and stitches

| Command | Does |
| --- | --- |
| `weave status [--impact <WS>]` | Workstream and head, your draft by symbol (`awaiting <owner>` for routed changes), edits not added, held edits, waiting stitches, change requests, resolution points, promotion status per stitch, parent weaves not received, suggestions, notices, unread messages. `--impact` also lists symbols changed differently in that workstream. |
| `weave status --symbols` | Only your draft, one line per symbol, with signatures before / after. Offline, no lock. |
| `weave add [PATHS]... [--adopt <PATH>]... [--allow-revert] [--allow-secret <PATH>]...` | Add edits from disk to your draft, by symbol (default `.`; also `file::symbol`). Stale copies are not edits; clashing real edits are routed when you stitch. `--adopt` takes files over from another session's draft. |
| `weave stitch -i <INTENT> [-w <WHY>] [-k <KIND>] [-y] [--only <TARGET>...] [--allow-revert] [--allow-secret <PATH>...]` | Seal your draft into one stitch and weave it. `-i` (alias `--title`, `-t`) is required; `-w` (alias `--message`, `-m`) is the why and drafts a decision record (`-y` records it without asking); `-k` prefixes a kind (`feat: …`); `--only` stitches only those files or symbols. |
| `weave stitch -i <INTENT> --paths <PATH>... [--also-session <S>]... [--keep-claims]` | Add, stitch and release claims in one command. |
| `weave stitch -i <INTENT> --sessions <S1,S2,...>` | Seal several sessions' drafts and weave them in one request; `{session}` in the intent is each session's name. |
| `weave drafts [--all-sessions]` | Drafts on this device: session, workstream, files, symbols, age, behind the head. |
| `weave draft drop <TARGETS>...` | Take changes out of your draft; files on disk go back to the head. |
| `weave hibernate` / `weave resume` | Park your draft and show the head / bring it back, carried forward. |
| `weave mv <FROM> <TO>` | Move a file (`a.rs b.rs`) or a symbol to another file (`a.rs::f b.rs`), keeping identity, owner and history. |
| `weave cat <PATH> [--workstream <WS>] [--draft]` | Print a file as weaved at a head (`--draft`: with your draft). |
| `weave push` | Submit stitches sealed while the server was unreachable. |

## Workstreams

| Command | Does |
| --- | --- |
| `weave workstream new <NAME> [--from <WS>] [--ownership repo\|workstream] [--inherit auto\|manual]` | Create a workstream (`--from` alias `--base`, default the active one) and switch to it. |
| `weave workstream list [--archived]` | Workstreams with parent, head, settings and weaved count; `*` marks the active one. |
| `weave workstream switch <NAME>` / `weave checkout <WS>` | Switch: render that head plus your drafts there to disk. Refuses while edits aren't added. |
| `weave workstream remove <NAME> [--force]` | Archive a workstream (alias `archive`). |
| `weave workstream restore <NAME>` | Bring a removed workstream back. |
| `weave timeline [WS] [--limit <N>]` | Weaved stitches, newest first (default 100). |
| `weave promote <STITCH> --to <WS> [--with-deps]` | Promote a weaved stitch (id prefix) to another workstream. |
| `weave refresh` | Receive the parent's weaves now (for `--inherit manual`). |
| `weave integrate <TARGET>` | Private integration draft from a change request or a workstream. |
| `weave cr list [--all]` / `show <ID>` / `resolve <ID> this\|other\|edit [--text <T> \| --from-file <P>]` | Change requests. |
| `weave revert <STITCH> --why <WHY>` | Take back a weaved stitch with a new stitch. |
| `weave seed --from <ORG/REPO> [--state <HASH> \| -w, --workstream <WS>]` | Fill the empty active workstream from a template, on the server. *(connected)* |
| `weave sync` | Fetch what was weaved and update files on disk; clashing un-added edits stay as `held`. *(connected)* |

## Ownership and review *(connected)*

| Command | Does |
| --- | --- |
| `weave claim <TARGETS>... [--feature <TEXT>] [--lease <SECS>] [--partial]` | Claim files, symbols or globs (`*`, `?`, `{` only). All or nothing unless `--partial`. |
| `weave claims [--all]` | Live claims in the active workstream's ownership scope (`--all`: every scope). |
| `weave release <TARGET>` / `weave release --all` | Release a claim / every claim you hold here. |
| `weave owners [PATHS]... [--fresh]` | Who owns files, symbols and JSON keys, part labels, leases. |
| `weave start "<INTENT>"` | Predict the symbols an intent touches and claim them. |
| `weave suggestions [list] [--all]` | Suggestions to you and yours (alias `suggestion`). |
| `weave suggestions show <ID>` / `accept <ID>` / `reject <ID> [--reason <T>]` / `resubmit <ID>` | Review or resend. |
| `weave resolutions [list [--all]]` / `show <TAG>` | Resolution points (alias `resolution`). |
| `weave resolve <TAG> head\|copy\|edit [--text <T> \| --from-file <P>] [--why <T>]` | Keep one version of a resolution point. |
| `weave watcher` | Start `weave-watcher` in the background: renews leases, keeps files on disk in step, prints messages and notices. |

## Messages *(connected)*

Alias `weave message`. Addresses: `@all`, `@ws:<ws>`, `@owner:<file>[::<symbol>]`, a user id or `agent:<id>`.

| Command | Does |
| --- | --- |
| `weave msg send <TO>... -m <TEXT> [--about <FILE[::SYMBOL]>] [--workstream <WS>] [--reply <ID>]` | Send (`-m -` reads stdin). With `--reply` and no `TO`, the answer goes to the sender. |
| `weave msg inbox [--all] [--sent] [--limit <N>]` | Unread messages (default limit 30). |
| `weave msg show <ID>` | The conversation, marked read. |
| `weave msg read <ID>...` / `--all` | Mark read. |
| `weave msg wait [--timeout <SECS>] [--from <USER>] [--after <ID>]` | Block until a message arrives (default 300 s); exit 2 on timeout. |

## History and undo

| Command | Does |
| --- | --- |
| `weave log [--actor <U>] [--by-agent <A>] [--workstream <WS>] [--symbol <FILE::SYMBOL>] [--limit <N>] [--verify]` | The operation log, newest first (default 30). |
| `weave undo [ENTRY]` | Reverse your own most recent action, or that log entry. |

## Orientation and search

| Command | Does |
| --- | --- |
| `weave outline [PATHS]... [--exports-only] [--budget <TOKENS>]` | What the files on disk define, with owners and whose draft changed them. |
| `weave context <FILE::SYMBOL> [--budget <TOKENS>]` | One card about a symbol (default 600 tokens). |
| `weave find <WORDS>... [--limit <N>]` | Keyword search over symbols on disk (default 20). |
| `weave search <QUESTION>... [--limit <N>] [--budget <TOKENS>] [--paths <PREFIX>,...]` | Semantic + keyword search (default 10 hits, 800 tokens). |
| `weave notices [--since <CURSOR>]` | Changes in other drafts that affect your code. |
| `weave contract declare <FILE::SYMBOL> --signature <TEXT> [--owner <PART>]` | Record a planned interface. |
| `weave contract check [--owner <PART>] [--strict]` / `remove <FILE::SYMBOL>` | Check contracts against disk / drop one. |

## Decisions and threads

| Command | Does |
| --- | --- |
| `weave decision add -t <TITLE> -w <WHY> [--on <SYMBOL>...] [--alt <T>]... [--constraint <T>]... [--comment]` | Record a decision. |
| `weave decision show <IDS>...` / `list [--all] [--status <S>]` | Read decisions. |
| `weave decision supersede <OLD> -t <T> -w <W> [...]` / `retire <ID> [--reason <T>]` | Replace / withdraw one. |
| `weave decision review [ID] [--accept] [--dry-run] [--candidates]` / `confirm <N> [-t <T>]` | Drift review; confirm an enrich candidate. |
| `weave decision for [SYMBOLS]... [--file <F>] [--radius <N>] [--budget <N>] [--all] [--format summary\|constraints]` | Decisions on symbols and their neighbours. |
| `weave decision search <QUERY> [--near <S>]... [--budget <N>] [--all]` / `impact <SYMBOL> [--depth <N>] [--budget <N>]` | Ranked search / callers and callees with decision counts. |
| `weave thread show\|add\|add-many\|remove\|list\|search\|heal …` | Behaviour notes per symbol. |
| `weave index` / `weave symbols [FILE]` | Local symbol index and call graph (nothing is sent). |
| `weave enrich [--full \| --file <F> [--symbol <S>]] [--yes] [--provider anthropic\|openai\|gemini] [--model <M>] [--key <K>]` | Draft thread entries with an LLM, on your machine with your key. |
| `weave enrichment-prompt get\|set "<TEMPLATE>"\|reset` | The prompt template for `enrich`. |

## AI agents

| Command | Does |
| --- | --- |
| `weave mcp` | MCP server over stdio. Use `weave --agent <name> mcp`. Tools: [For AI agents](https://www.weave.directory/docs/agents#every-mcp-tool). |

## Not working yet

`weave heatmap` (no feed provides it yet) and `weave checkout --sparse <SYMBOL>` (the server doesn't answer impact-radius queries yet).

## Retired commands

`queue`, `pull`, `strand`, `docs`, `shim`, `debt`, `heal`, `propose`, `accept-contract` print a pointer to their replacement; `inbox` still runs `weave suggestions list`.

| Retired | Use instead |
| --- | --- |
| `queue` | `weave stitch` (waiting stitches show in `weave status`) |
| `pull` | `weave sync`, `weave refresh` or `weave integrate <workstream>` |
| `strand` | `weave workstream new <name> --from <workstream>` |
| `docs` | `weave decision add` or `weave stitch --why` |
| `shim`, `debt`, `heal` | Signature-change notices (`weave status`, `weave notices`); `weave thread heal` |
| `propose` | Edit and stitch: changes to owned symbols become suggestions |
| `accept-contract` | `weave suggestions accept <id>` |

## Environment variables

A `.env` file in the current directory is loaded automatically.

| Variable | Purpose |
| --- | --- |
| `WEAVE_TOKEN` | Personal access token or agent token (`wva_…`); overrides the saved one. Enough on its own for `clone`, `add`, `stitch` and `sync`. |
| `WEAVE_AGENT`, `WEAVE_AGENT_MODEL` | Act as an AI agent (same as `--agent`, `--agent-model`). |
| `WEAVE_SERVER_URL`, `WEAVE_PLATFORM_URL` | Override the service URLs (defaults `https://api.weave.directory`, `https://www.weave.directory`). |
| `WEAVE_REPO_ID` | Platform repository id for this checkout. |
| `WEAVE_USER` | Author name in local mode. |
| `WEAVE_DECISION_YES` | `1`: record drafted decisions without asking. |
| `WEAVE_OWNERS_MAX_AGE_SECS` | Maximum age of the local claims copy for `owners` / `outline` (default 15). |
| `WEAVE_NO_DAEMON` | `1`: run the command by itself even when `weave serve` runs. |
| `WEAVE_SOCKET` | Socket of the `weave serve` to use. |
| `WEAVE_DEBUG_SERVE` | `1`: say on stderr why a command didn't use `weave serve`. |
| `WEAVE_MCP_LOG` | Log filter for `weave mcp` (default `info`). |
| `WEAVE_LOCK_LOG` | File to append one JSON line to per lock released. |
| `WEAVE_REQUEST_LOG` | File to append one line to per server round trip. |
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` | Keys for `weave enrich`. |

URLs resolve, first match wins: the environment variable, `.weave/config.json`, `~/.weave/config.json`, the default. The repository resolves from `WEAVE_REPO_ID`, then `repo_id` or `repo` in `.weave/config.json`, then the `origin` remote.

## Files

| Path | Holds |
| --- | --- |
| `~/.weave/config.json` | `token`, `platform_url`, `username`, `server_url`, `skip_wired_platforms` |
| `.weave/config.json` | `mode`, `server_url`, `remotes`, `repo_id` / `repo`, `kinds` |
| `.weave/drafts/<session>/` | Private drafts |
| `.weave/decisions/` | Decision records (stitched with the code) |
| `.weave/contracts.toml` | Contracts (local) |
| `.weave/locks/`, `.weave/lock` | Session locks and the checkout-wide lock |
| `.weave/serve.log` | Log of `weave serve --detach` |
| `.weaveignore` | Ignore patterns. Built in: `.git`, `.weave`, `target`, `node_modules`, `dist`, `build`, `.next`, `.nuxt`, `.cache`, `.idea`, `.vscode`, `coverage`, `.DS_Store` |