CLI and Configuration Reference

CLI and Configuration Reference

Language: English · 简体中文

LWC is a JSON-first command-line interface. Successful commands write JSON to standard output; failures write a structured JSON error to standard error and exit non-zero. This page maps command families to their purpose. The installed command's --help output is authoritative for exact flags and examples.

Invocation model

lwc [--scope project|global|all] [--changeset <name>] <command>

• project is the default and discovers the nearest ancestor .lwc/wiki.db.
• global selects the user Wiki at ~/.lwc/wiki.db.
• all is read-only and supported only by search and context.
• --changeset routes supported operations to one isolated draft.

Run lwc directly from PATH. Do not routinely export LWC_PROJECT_ROOT or assign an absolute binary path. Set LWC_PROJECT_ROOT only to place an intentional discovery boundary around a selected project.

Configuration model

Configuration is deployment-local JSON layered as built-in defaults, global settings, then project overrides. It is not Wiki knowledge and does not participate in changesets.

lwc --scope project config show
lwc --scope project config set --graph grafeo
lwc --scope project config set --trans markitdown --trans-timeout 120
lwc --scope project config unset --graph --trans

Supported graph settings are disabled, grafeo, and surrealdb. Supported conversion settings are disabled, markitdown, and anydoc. An unset project field inherits the global value; an explicit disabled blocks inheritance. Always read the returned effective configuration and origin instead of inferring behavior from one file.

For adapter arguments, combined atomic updates, safety rules, and verification, see Capability configuration.

Command families

Command	Purpose	Primary guide
init	Initialize the selected Wiki and materialize owned files	Quick start
source	Collect, inspect, diff, reference, and remove immutable evidence	Sources and ingestion
ingest	Move Sources through the persistent analysis workflow	Sources and ingestion
page	Create, inspect, link, and remove compiled knowledge	Wiki Pages and provenance
schema, purpose	Define the Wiki's content contract and mission	Persistent memory
search, span, context	Retrieve documents or bounded context	Search and context
tag, load	Curate and strongly load core Page sets	Tags and strong context
weight	Apply explicit ranking weights or retrieval feedback	Search ranking and indexing
graph	Query and maintain the physical document graph	Document knowledge graph
cg	Install, initialize, and inspect CodeGraph	Code graph
trans	Convert an external document to a new Markdown file	Document conversion
changeset	Stage and publish an atomic multi-command change	Changesets
work	Inspect, watch, cancel, and resume durable background work	Work system
checkpoint	Create or restore a full Store snapshot	Checkpoints and rollback
maintenance	Rebuild projections, reindex search, or compact storage	Recovery and maintenance
lint, log	Validate structure and inspect durable operation history	Troubleshooting-and-FAQ
view	Open the loopback-only read-only Viewer	Read-only Viewer
serve --mcp	Serve the standard Agent-facing MCP transport	MCP server and lwc_explore

Source workflow

lwc --scope project source add docs/design.md --title "Design specification"
lwc --scope project ingest next --source-max-chars 100000
lwc --scope project ingest analyze <source-id> --file analysis.md
lwc --scope project page put source-<source-id> \
  --title "Design specification" --kind source \
  --file summary.md --source <source-id>
lwc --scope project page put architecture \
  --title "Architecture" --kind concept \
  --file architecture.md --source <source-id>
lwc --scope project ingest complete <source-id>
lwc --scope project lint

source add collects evidence; it does not make that evidence integrated knowledge. Complete the ingest state machine and write cited Pages.

Useful Source subcommands are add, add-dir, add-manifest, list, status, diff, show, refs, and remove. Use --allow-external-source only for an intentionally authorized path outside the project.

Retrieval workflow

lwc --scope project search "rollback graph projection" --limit 10 --explain
lwc --scope project search "exact sentence" --granularity sentence
lwc --scope all context --limit 25
lwc --scope project span get <span-id>
lwc --scope project span expand <span-id> --children 10

Search defaults to compiled Pages with Source fallback. --type, --kind, --granularity, and --group-by narrow the result model. --record is the explicit switch that persists a query operation.

Page and tag workflow

lwc --scope project page put operations-policy \
  --title "Operations policy" --kind policy \
  --file operations-policy.md --source <source-id>
lwc --scope project tag set rules operations-policy \
  --priority 100 --reason "Mandatory operating boundary"
lwc --scope project tag autoload rules --enable \
  --priority 100 --limit 10 --max-chars 50000 \
  --reason "Load at Agent lifecycle boundaries"
lwc --scope project load tag rules --limit 10

Tag membership and autoload policy are separate records. load tag returns complete Pages in deterministic priority order; it is not search.

Graph workflow

lwc --scope project config set --graph grafeo
lwc --scope project work watch <work-id>
lwc --scope project graph verify
lwc --scope project graph related page:architecture --limit 20
lwc --scope project graph path page:architecture source:<source-id> --max-depth 4
lwc --scope project cg init
lwc --scope project cg status

Document graph and CodeGraph are independent. A queued Work is not readiness: wait for terminal success, then verify the document graph or inspect CodeGraph status.

Atomic update workflow

lwc --scope project changeset begin release-policy
lwc --scope project --changeset release-policy page put release-policy \
  --title "Release policy" --kind policy \
  --file release-policy.md --source <source-id>
lwc --scope project --changeset release-policy lint
lwc --scope project changeset show release-policy
lwc --scope project changeset commit release-policy

Use discard before commit. Use rollback <changeset-id> only for the exact committed transaction and follow any returned graph Work. Do not use --allow-lint-issues to hide false positives or incomplete content.

Durable Work

lwc --scope project work list
lwc --scope project work status <work-id>
lwc --scope project work watch <work-id>
lwc --scope project work cancel <work-id>
lwc --scope project work resume <work-id>

State-changing maintenance and graph projection return Work metadata. watch is the normal completion boundary. Cancellation is cooperative; watch until cancelled before assuming execution stopped.

Viewer, Hook, and MCP transports

lwc --scope project view --no-open --port 0
lwc agent hook --agent codex --event SessionStart
lwc serve --mcp --path /absolute/project/path

Viewer startup and shutdown are foreground process events. Hook mode reads the host's event envelope from standard input. MCP uses newline-delimited JSON-RPC on standard input and output; do not mix human logging into that stream.

Machine-readable error handling

if ! output=$(lwc --scope project lint 2>error.json); then
  jq -r '.error.code' error.json
  jq '.error.details' error.json
fi

Automations should branch on error.code, inspect error.details, and preserve the process exit status. Never parse localized prose or assume that an error means nothing changed: recovery errors may report canonical partial success.

See JSON output and error contract and Scopes and project discovery.