This directory no longer defines one combined weaveback binary. The CLI is split across four focused tools:

  • `wb-tangle` for tangling and apply-back

  • `wb-query` for attribution, search, coverage, cargo diagnostics, tagging, and LSP queries

  • `wb-serve` for the local docs server

  • `wb-mcp` for MCP / agent integration

The role of cli-spec/ is now narrower and easier to read, but it is still fully generative:

  1. `macros.adoc` defines shared option-family macros

  2. each standalone CLI spec imports those macros and generates its own cli_generated.rs

  3. this file generates the public cross-binary CLI reference page

PlantUML diagram

Generated CLI reference

// <<@file docs/cli.adoc>>=
= CLI reference

The old combined `weaveback` binary is gone. The public CLI is now split into
four focused tools.

== Command map

[cols="1,3",options="header"]
|===
| Tool | Responsibility

| `wb-tangle`
| Build-side operations: single-pass tangling, multi-pass `weaveback.toml`
  runs, and `apply-back` reconciliation from `gen/` to literate source.

| `wb-query`
| Read/query-side operations: `where`, `trace`, `attribute`, `impact`,
  `graph`, `search`, `lint`, `coverage`, wrapped `cargo`, `tags`, plus
  semantic `lsp` lookups and `tag` metadata generation.

| `wb-serve`
| Local docs server with live reload, inline editing, and AI-assisted views.

| `wb-mcp`
| MCP server for editor and agent integrations.
|===

== Migration from the old combined CLI

[cols="2,3",options="header"]
|===
| Old command | New command

| `weaveback file.adoc --gen gen`
| `wb-tangle file.adoc --gen gen`

| `weaveback --dir src --gen gen`
| `wb-tangle --dir src --gen gen`

| `weaveback tangle`
| `wb-tangle`

| `weaveback apply-back`
| `wb-tangle apply-back`

| `weaveback where ...`
| `wb-query where ...`

| `weaveback trace ...`
| `wb-query trace ...`

| `weaveback attribute ...`
| `wb-query attribute ...`

| `weaveback cargo ...`
| `wb-query cargo ...`

| `weaveback coverage ...`
| `wb-query coverage ...`

| `weaveback graph ...`
| `wb-query graph ...`

| `weaveback impact ...`
| `wb-query impact ...`

| `weaveback search ...`
| `wb-query search ...`

| `weaveback lint ...`
| `wb-query lint ...`

| `weaveback tag ...`
| `wb-query tag ...`

| `weaveback tags ...`
| `wb-query tags ...`

| `weaveback lsp ...`
| `wb-query lsp ...`

| `weaveback serve ...`
| `wb-serve ...`

| `weaveback mcp`
| `wb-mcp`
|===

== Common workflows

=== Build and regenerate outputs

[source,bash]

wb-tangle --dir src --ext adoc --include . --gen src wb-tangle

=== Reconcile edits made in `gen/`

[source,bash]

wb-tangle apply-back wb-tangle --gen path/to/gen apply-back --dry-run

=== Trace generated code back to literate source

[source,bash]

wb-query where gen/out.rs 120 wb-query trace gen/out.rs 120 8 --include . wb-query attribute gen/out.rs:120:8 --include .

=== Coverage and diagnostics

[source,bash]

wb-query cargo clippy --all-targets — -D warnings wb-query coverage --summary lcov.info

=== Docs server and MCP

[source,bash]

wb-serve --watch wb-mcp

== Detailed references

For full flag-by-flag details, read the tool-specific pages:

* link:../crates/wb-tangle/src/main.adoc[`wb-tangle`]
* link:../crates/wb-query/src/main.adoc[`wb-query`]
* link:../crates/wb-serve/src/main.adoc[`wb-serve`]
* link:../crates/wb-mcp/src/main.adoc[`wb-mcp`]
* link:../cli-spec/macros.adoc[`cli-spec/macros.adoc`] for the shared option
  families used by the generated CLI code
// @