Weave CLI Commands

Print the version

weave --version
weave-watcher --version

Both print 0.1.0 for this release.

Initialize a repository: local mode, connected to the hosted service, or interactive

weave init [--local | --server <url>]

Log in before --server. Without a flag in a terminal, a wizard asks “Where should workstreams live?”: “Connect to a Weave server (URL)” (default; the URL defaults to https://api.weave.directory unless WEAVE_SERVER_URL or a config sets another) or “Local only (this device)”, then offers to wire AI agents (Claude Code, Gemini CLI, Cursor, Codex) to weave mcp. Without a terminal it stays local. Running init again keeps your workstreams.

Log in with a Personal Access Token from your Weave account

weave login [--url <platform>]

Create the token at www.weave.directory under Settings → Access Tokens. Prompts “Enter your Personal Access Token” (or reads it from stdin), checks it, and saves token, platform_url (and the older url key) to ~/.weave/config.json. Without --url it uses WEAVE_PLATFORM_URL, then platform_url in .weave/config.json, then platform_url or the older url in ~/.weave/config.json, then https://www.weave.directory. WEAVE_TOKEN overrides the saved token.

Set a key in the global config (~/.weave/config.json)

weave config <key> <value>

Values are stored as strings, e.g. weave config platform_url https://www.weave.directory or weave config server_url https://api.weave.directory to undo an older setup.

Name the repository on the hosted service (its org/name identifies it)

weave remote add <name> <url>
weave remote list

Writes .weave/config.json, so run weave init first. The origin remote (or the only one) is used; not needed when your account can access exactly one repository.

List or edit ignore patterns (.weaveignore)

weave ignore [list]
weave ignore add <pattern>
weave ignore remove <pattern>

Upgrade a legacy .weave/ (also automatic)

weave migrate

Your draft by symbol, edits not added, stitches waiting, change requests, promotion status

weave status [--impact <workstream>]

Add edits from files on disk to your private draft, by symbol

weave add [<path> | <dir> | . | <file::symbol>]...

Seal your draft into a stitch and weave it

weave stitch -i "<intent>" [-w "<why>"] [-k <kind>] [-y] [--only <file|file::symbol>...]

-i/--intent (alias --title), -w/--why (alias --message), -k/--kind is prefixed to the intent, -y records the drafted decision without asking, --only seals part of the draft.

Drop changes from your draft (files on disk go back to the workstream’s version)

weave draft drop <file::symbol|file|dir>...

Print a file as weaved at a workstream head (or with your draft)

weave cat <path> [--workstream <ws>] [--draft]

Move a file or a symbol as an explicit move in your draft

weave mv <from> <to>

a.rs b.rs moves a file; a.rs::f b.rs moves a symbol. Thread sidecars move along.

Park your draft (files on disk show the weaved head) / bring it back, carried forward

weave hibernate
weave resume

Manage allowed stitch kinds (feat, fix, docs, style, refactor, test, chore, change)

weave kinds list
weave kinds add <name>
weave kinds remove <name>

Create a workstream from a parent and switch to it

weave workstream new <name> [--from <workstream>] [--ownership repo|workstream] [--inherit auto|manual]

--from (alias --base) defaults to the active workstream; ownership defaults to repo, inherit to auto.

List workstreams / switch

weave workstream list
weave workstream switch <name>
weave checkout <workstream>

Switching renders the head plus your draft there to files on disk; it refuses when files have edits that are not added.

Weaved stitches, newest first

weave timeline [<workstream>] [--limit 100]

Promote a weaved stitch to another workstream (usually the parent)

weave promote <stitch> --to <workstream> [--with-deps]

Receive the parent’s weaved stitches now (inherit = manual)

weave refresh

Build a private integration draft from a change request or workstream

weave integrate <change-request|workstream>

Change requests

weave cr list [--all]
weave cr show <id>
weave cr resolve <id> this|other|edit [--text "<text>" | --from-file <path>]

this keeps the workstream’s version, other takes the incoming one, edit takes the symbol as edited on disk (or --text / --from-file). Then stitch.

Take back a weaved stitch with a new stitch of inverse operations

weave revert <stitch> --why "<why>"

Operation log: what every person and agent did, newest first

weave log [--actor <user>] [--by-agent <agent>] [--workstream <ws>] [--symbol <symbol>] [--limit 30] [--verify]

Reverse your own most recent action (or a chosen log entry)

weave undo [<entry>]

Claim symbols, files or globs (all-or-nothing, under a lease)

weave claim <file::symbol|file|glob>... [--feature "<what for>"] [--lease <secs>]

Globs are expanded locally. The lease defaults to 10 minutes; a running weave watcher renews it.

Live claims in the active workstream’s scope (or every scope)

weave claims [--all]

Release a claim, or all of yours

weave release <file|file::symbol>
weave release --all

Declare an intent: the service predicts and claims the symbols it touches

weave start "<intent>"

Suggestions: changes to symbols you own, and yours to others’

weave suggestions [list [--all]]
weave suggestions show <id>
weave suggestions accept <id>
weave suggestions reject <id> [--reason "<reason>"]
weave suggestions resubmit <id>

Fetch new weaves and update files on disk (never overwriting edits not added)

weave sync

Submit stitches sealed while the service was unreachable

weave push

Background watcher: renews leases, syncs files on disk, re-indexes saved files for search

weave watcher

Run it in the checkout: it starts weave-watcher (next to weave, else on PATH) in the background and prints its pid; stop it by ending that process. weave-watcher itself only takes --version and --help.

Record a decision anchored to symbols (added to your draft)

weave decision add -t "<title>" -w "<why>" --on <symbol>... [--alt "<alternative>"] [--constraint "<constraint>"] [--comment]

Title ≤80 characters, why ≤240. --comment inserts a one-line "why: … [D-xxxx]" comment above each anchor.

Show or list records

weave decision show <id>...
weave decision list [--all] [--status active|needs_review|superseded|stale|retired]

Replace or withdraw a decision

weave decision supersede <old> -t "<title>" -w "<why>" [--on <symbol>...]
weave decision retire <id> [--reason "<reason>"]

Drift review and enrich candidates

weave decision review [<id> --accept] [--dry-run] [--candidates]
weave decision confirm <n> [-t "<title>"]

Budgeted retrieval

weave decision for <symbol>... [--file <path>] [--radius 1] [--budget 800] [--all]
weave decision search "<query>" [--near <symbol>] [--budget 600] [--all]
weave decision impact <symbol> [--depth 1] [--budget 500]

Index symbols and the call graph (pushed to the hosted service for search when connected)

weave index

List symbols in a file or the project

weave symbols [<file>]

Threads: short per-symbol behaviour notes

weave thread show <symbol> [--file <path>] [--depth N]
weave thread add <symbol> "<entry>" [--file <path>]
weave thread add-many [--from <file.json>]
weave thread remove <symbol> [--file <path>] [--idx N | --all]
weave thread list
weave thread search "<terms>" [--limit 20]
weave thread heal [--dry-run] [--apply-all]

LLM-proposed baseline thread entries (your own key)

weave enrich [--full | --file <path> [--symbol <name>]] [--yes] [--provider anthropic|openai|gemini] [--model <name>] [--key <key>]
weave enrichment-prompt get|set "<template>"|reset

MCP server over stdio for AI agents

weave mcp

Tools: decisions_for, decision_search, decision_get, impact, decision_propose, decision_review, thread_show, thread_add, thread_add_many, thread_list, thread_search, symbol_list.

Install or refresh the weave pointer in CLAUDE.md

weave install-claude

Then: claude mcp add weave -- weave mcp