The Vocabulary of
Action.
Every command follows the same shape: weaver <resource> <verb> [FLAGS]. Resources are nouns – symbols, patches, diagnostics – and the verbs come from one canonical set: get, list, apply, rename, move, and friends. One readable renderer, one stable --json contract.
This surface is the v0.1.0 target (ADR 007). The prototype observe / act / verify grammar, root --output, per-operation --format, and root --capabilities are superseded and will not ship.
Command Families
| Family | Purpose | Key Commands |
|---|---|---|
| Read | The code-reading loop: definitions, references, diagnostics, symbol cards, and budgeted graph slices. | definitions get, references list, diagnostics list, cards get, graph-slices get |
| Query | Structural selection via Sempai. Emits versioned selector streams that pipe into any consumer. | symbols list --query | --expr | --rule (each with -file and stdin forms) |
| Change | The safe change loop: one shared mutation engine behind every actuator, Double-Lock verified. | patches apply, symbols rename, symbols move |
| Introspection | The whole command contract, as data. Help, manpages, and completions generate from the same source. | context --json, capabilities list |
| Workflow | Compounding agent primitives: saved profiles, durable jobs, delivery sinks, and structured feedback. | profiles save, jobs list --wait, feedback create |
| Lifecycle | Daemon control. The daemon auto-starts on demand; these are the manual escape hatches. | daemon start, daemon status, daemon stop |
Read
perception
The agent's eyes. Definitions, references, and diagnostics from LSP and Tree-sitter, plus symbol cards with bounded one-hop context.
$ weaver definitions get \
--uri file:///src/main.rs --position 10:5
Change
actuation
The agent's hands. Patches, renames, and symbol moves through one shared mutation engine – every edit Double-Lock verified before it touches disk.
$ weaver patches apply \
--file fix.patch --dry-run
Verification
the conscience
The agent's conscience. The Double-Lock runs inside every mutation; diagnostics list is the standalone read on workspace health.
$ weaver diagnostics list \
--workspace .
The Selector Pipeline
Query, filter, mutate: how a refactor moves through the shell. A human, jq, or an agent can stand at any join.
Query Symbols
A structural pattern selects every matching function. Matches leave as a deterministic selector stream, closed by a completion record.
--lang rust \
--query 'fn $NAME($...ARGS)' --json
// one JSONL record per match, then exactly one completion record
{"schema":"weaver.selector.v1","uri":"file:///src/lib.rs","language":"rust","span":{"start":1042,"end":1187},"captures":{"NAME":{"text":"old_run"}},"source":{"digest":"sha256:9f2c..."}}
{"schema":"weaver.selector-stream-end.v1","matches":1,"complete":true}
Plan the Rename
Selectors pipe straight into an actuator. The actuator reads the complete stream, validates the completion record, and only then plans – --dry-run shows the plan without committing.
--selectors - --new-name run --dry-run
// the plan, not the commit
{"dry_run":true,"operations":3,"files":["src/lib.rs","src/main.rs","tests/run.rs"],"verification":{"syntactic":"ok","semantic":"ok"}}
Commit, Verified
Dropping --dry-run commits atomically. The result carries the transaction, digests, and the diagnostics delta – and stale sources are refused, twice.
--selectors - --new-name run --json
// transaction result with the diagnostics delta
{"transaction":"txn_01j9...","changed":["src/lib.rs","src/main.rs","tests/run.rs"],"diagnostics":{"introduced":0,"resolved":0,"unchanged":12}}
Global Flags
Keep command semantics on this page. Keep config defaults, override precedence, and the wire protocol in the docs hub.
| --json | The one machine switch. Emits the stable JSON contract for the command; without it, the localized human renderer applies. |
| --plain / --color / --width / --no-pager / --locale | Human-renderer controls. Colour never carries meaning alone; ASCII and narrow-width fallbacks are first-class. |
| --profile | Select a saved profile. Precedence: built-in defaults < config files < profile < environment < flags. Secrets are redacted on output. |
| --config-path | Path to an explicit weaver.toml configuration file. |
| --daemon-socket | Override the local daemon endpoint. Unix domain sockets are the Unix default; prototype TCP compatibility is loopback-only. |
| --dry-run / --force | Standard mutation safety flags. --force never overrides a stale-source refusal; an override must name the newly accepted source version. |
Exit Codes & Errors
| 0 | Success – including a query with zero matches, which still emits its completion record. |
| 1 | General error (file not found, permission denied). |
| 126 | Command invoked cannot execute (sandbox restriction). |
| 130 | Terminated by signal (Ctrl-C). |
Errors teach. Every enum-shaped rejection names the invalid value, the valid values and their source registry, a stable error code, an exit class, and a working next command. Guessing is not part of the contract.
Introspection & Output
This page keeps the command map. The authoritative defaults, override syntax, and wire envelope live in the docs hub so those details only drift in one place.
The contract, as data
weaver context --json emits the whole surface: schema version, commands, flags, enum values, output schemas, error taxonomy, and capabilities. Agents read it once and stop guessing.
Capability probe
weaver capabilities list --json reports runtime availability with a deterministic provider-selection rationale. Providers stay behind capabilities; their names surface only in provenance and verbose output.
Non-interactive by default
No implicit prompts. Interaction happens only under --interactive or a dedicated review command, and a non-TTY stdin fails fast with a structured error.
CLI Help & Discoverability
Planned
Help text, manpages, and shell completions all generate from the single command contract behind context --json, with drift gates in CI. One source; no stale runbooks.
| Command | Behaviour |
|---|---|
| weaver --help | Lists every resource and its verbs, plus global options and a quick-start example. Does not require a running daemon. |
| weaver <resource> | Without a verb, prints the verbs available for that resource and a follow-up --help hint. |
| weaver <resource> <verb> --help | Command-level help with required arguments, examples, and exit codes. |
| weaver skill-path | Prints the paths to agent-facing skill documents shipped with the binary. |
Actionable Errors
An invalid resource lists all valid resources. An unknown verb suggests the nearest match. Every error path follows the same three-part template: problem statement, valid alternatives, and an explicit next command.