Reference

CLI reference

Every weave command grouped by task, with flags, JSON output and environment variables.

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.

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.
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). 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.

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`