The Weave CLI is the user-facing command surface for creating, validating, and managing Weave configuration. It creates .weave configuration directories and safely hands Weave intent to supported harness installers. It does not start, supervise, or drive third-party harness runtimes.

Note: weave run is not supported. Weave configures harnesses; harnesses run themselves. Use weave init and harness-specific launch commands instead.

Install the Weave CLI package with Bun:

bun install
bun run build
bun link ./packages/cli
command -v weave
weave --help

Or use package runners once @weaveio/weave-cli is published:

bunx @weaveio/weave-cli --help
npx @weaveio/weave-cli --help
pnpm dlx @weaveio/weave-cli --help

The CLI renders a colorful WEAVE banner when terminal color is supported. To disable color output:

NO_COLOR=1 weave --help

When color is disabled or stdout is not a TTY, output remains readable plain text.

Creates a starter Weave config directory containing config.weave and prompts/. See the DSL Configuration guide for configuration syntax.

weave init [--scope <scope>] [--install-dir <path>] [--harness <name>] [--all-harnesses] [--force] [--yes]

• Existing config.weave is skipped by default
• --force writes config.weave.bak before overwriting
• --yes / -y accepts safe defaults without prompts
• Non-TTY invocations do not hang; use decisive flags such as --scope and --yes in scripts
• Prompt cancellation exits cleanly with code 0

# Interactive local init
weave init --scope local

# Non-interactive global init
weave init --scope global --yes

# Custom directory
weave init --scope local --install-dir ./custom-weave --yes

# Install for specific harness
weave init --harness opencode --yes

# Install for all detected harnesses
weave init --all-harnesses --yes

✓ Created .weave/config.weave
✓ Created .weave/prompts/
✓ Weave configuration initialized

Next steps:
  weave validate
  weave prompt list

Converts a legacy OpenCode JSONC config (weave-opencode.jsonc) into the current .weave DSL. Migration is also offered automatically during ordinary weave init when a legacy source file is detected for the chosen scope.

weave init migrate [--scope <scope>] [--yes]

Explicit migrate mode - direct invocation:

weave init migrate --scope local
weave init migrate --scope global
weave init migrate --scope local --yes
weave init migrate --scope global --yes

Ordinary init discovery - migration is offered after scope selection when the legacy source exists:

weave init --scope local   # offers migration if .opencode/weave-opencode.jsonc exists
weave init --scope global  # offers migration if ~/.config/opencode/weave-opencode.jsonc exists
weave init --yes           # auto-migrates non-interactively when legacy source is found

Migration always writes to the canonical Weave config paths:

Note: --install-dir is ignored in migrate mode. Migration always writes to the canonical scope destination to ensure the config loader can discover the file at runtime.

Before any file is written, migration shows a preflight summary:

Migration preflight

  Source:         /project/.opencode/weave-opencode.jsonc
  Destination:    /project/.weave/config.weave
  Scope:          local
  Overwrite:      no (destination does not exist)
  Skipped fields: none

When the destination already exists:

Migration preflight

  Source:         /project/.opencode/weave-opencode.jsonc
  Destination:    /project/.weave/config.weave
  Scope:          local
  Overwrite:      yes - backup will be created at /project/.weave/config.weave.bak
  Skipped fields: 2 field(s) will be skipped with warnings

• Validation before write: generated .weave DSL is validated through the normal parseConfig() pipeline before any file is mutated. If validation fails, migration aborts with no destination or backup written.
• Overwrite backup: when the destination already exists, exactly one backup is written at <destination>.bak before the destination is overwritten.
• Source preservation: the legacy JSONC source file is never renamed or deleted after successful migration.
• Provenance comment: generated config.weave begins with a comment block naming the legacy source, scope, and generator.
• JSONC comment stripping: arbitrary comments from the legacy JSONC source are not preserved in the generated DSL. Only structured field values are converted.

Migration uses best-effort partial conversion: supported fields are written even when some legacy fields are skipped. When fields are skipped, a warning summary is printed after the success message:

⚠  Migration warnings - the following legacy fields were skipped:

  • workflows: legacy workflow definitions are not supported in migration v1; define workflows using the current DSL workflow syntax
  • continuation: legacy continuation settings are not supported in migration v1; use the current DSL continuation block if needed
  • custom_agents.loom: "loom" collides with a builtin agent name; skipped to avoid silently overriding the builtin
  • agents.shuttle.tools.call_weave_agent: "call_weave_agent" is a harness-specific tool name that cannot be mapped to an abstract tool_policy capability; skipped

Exit code: migration exits with code 0 even when warnings are emitted, as long as the destination file was written successfully.

Explicitly skipped in migration v1 (warn + skip): workflows, continuation, analytics, background.

• agents entries are treated as overrides of existing builtin agent names (loom, tapestry, shuttle, pattern, thread, spindle, weft, warp). Non-builtin names under agents are warned and skipped.
• custom_agents entries become new agent <name> blocks when the name does not collide with a builtin. Collisions are warned and skipped.
• categories become category <name> blocks. The current DSL generates shuttle-<category> semantics automatically.

prompt_file values are preserved only when the path is a bare filename with no directory separators (e.g. "loom.md"). Paths with directory components (e.g. "subdir/loom.md", "/abs/path.md", "../prompts/loom.md") cannot be safely translated to the current .weave/prompts/ convention and are warned and skipped.

After a successful migration write, weave init migrate continues into the normal harness selection and configuration flow. This matches the behavior of ordinary weave init - migration is not a terminal command.

Validates effective, scoped, or explicit Weave config. See the DSL Configuration guide for configuration syntax and structure.

weave validate [--project | --global | --path <file>] [--json]

# Validate effective config for the current project
weave validate

# Validate project config only
weave validate --project

# Validate global config only
weave validate --global

# Validate specific file
weave validate --path file.weave

# JSON output
weave validate --path file.weave --json

Human-readable success output summarizes counts only:

✓ Valid Weave configuration

  Agents:     8
  Categories: 3
  Workflows:  2
  Disabled:   1 agent, 2 skills
  Log level:  info

The CLI intentionally avoids printing full private prompt/config content in normal success output. Parse and validation failures use file:line:column: message formatting where the DSL pipeline provides location data.

Inspects composed agent prompts or lists available agent names from the effective config. See the Agents guide for information about agent roles and the Prompt Composition guide for how prompts are composed.

weave prompt <subcommand> [--json]

Prints available agent names, including generated category shuttle agents.

weave prompt list
weave prompt list --json

Expected output:

Available agents:

  loom
  tapestry
  shuttle
  shuttle-backend
  shuttle-frontend
  pattern
  thread
  spindle
  weft
  warp

Renders the fully composed prompt for the requested agent.

weave prompt inspect loom
weave prompt inspect loom --json

Expected output:

Agent: loom

# Role

You are **loom**, the orchestration coordinator...

[Full composed prompt text]

Running weave prompt without a subcommand prints inline usage and exits with code 1.

Prints a deterministic, text-only guide that tells an agent exactly which files to read, what rules to follow, and how to verify changes when modifying Weave’s own configuration.

weave prompt self-modify [--scope <scope>]

The printed guide includes:

• The selected scope label (global (~/.weave/) or local (.weave/))
• The canonical config file path and prompts directory path for the scope
• A pre-flight checklist naming docs/dsl-reference.md and docs/config-loading.md as required reading
• A note that docs/prompt-composition.md must be read before any prompt-related change
• A clear statement that packages/docs/ is a public mirror, not the canonical source - the authoritative docs live in docs/ at the repo root
• Target-aware rules (global vs. local scope differences)
• A step-by-step workflow: identify → read DSL section → edit config → place prompt files → validate → inspect
• Common DSL patterns (override builtin, add agent, add category, disable agent)
• Prompt-specific rules (Mustache context fields, {{{delegation.section}}}, mutual exclusivity of prompt/prompt_file)
• Verification commands (weave validate, weave prompt list, weave prompt inspect)

# Guide for global scope (default)
weave prompt self-modify

# Explicit global scope
weave prompt self-modify --scope global

# Guide for project scope
weave prompt self-modify --scope local

Composes agent prompts with adapter-specific formatting.

weave compose --adapter <adapter> <agent>

weave compose --adapter claude-code loom

Inspects runtime status and journal entries.

weave runtime <subcommand>

Shows current runtime status.

weave runtime status

Expected output:

Runtime status:

  Harness:  opencode
  Version:  1.0.0
  Status:   running
  PID:      12345

Shows recent runtime journal entries.

weave runtime journal

Expected output:

Runtime journal:

  2026-08-27 10:30:15  [info]  Session started
  2026-08-27 10:30:16  [info]  Loaded config from .weave/config.weave
  2026-08-27 10:30:17  [info]  Agent loom initialized

Executes agent evaluation suites against the built-in model matrix. This is the primary eval entry point for CI and local verification.

weave eval run [--agent <agent>] [--model <model>] [--case <case>] [--dry-run] [--raw-artifacts]

The current eval surface is a shared eight-suite text-only registry:

export OPENROUTER_API_KEY=<your-key>

OPENROUTER_API_KEY must be set before running weave eval run. The runner validates it at startup and aborts immediately if absent or empty. The key value is never logged, printed, or serialized anywhere in the eval pipeline.

Exception: weave eval run --dry-run does not build live model clients and does not require OPENROUTER_API_KEY.

All three filters use strict exact-match:

• --agent must match either the suite name or the short agent name. No other values are accepted.
• --model must exactly match a model id in evals/model-matrix.json. No substring matching.
• --case must exactly match the id field in a case fixture file. No glob or prefix matching.

No filter means all values in that dimension are included. A no-filter run executes all three default models against all cases in all registered suites.

Filters can also be supplied via environment variables - useful in CI workflow dispatch:

WEAVE_EVAL_AGENT=loom weave eval run
WEAVE_EVAL_MODEL=anthropic/claude-sonnet-4.5 weave eval run
WEAVE_EVAL_CASE=loom-route-backend-api weave eval run

CLI flags and env vars are merged. Conflicting values for the same filter key (CLI vs env) cause a hard DuplicateConflictingInput error. Same-value duplicates are silently collapsed. Empty env filter values are treated as unset.

# Run all suites against default models (3)
weave eval run

# Restrict to loom-routing suite
weave eval run --agent loom

# Restrict to tapestry-execution and tapestry-category-routing suites
weave eval run --agent tapestry

# Restrict to tapestry-category-routing suite only
weave eval run --agent tapestry-category-routing

# Restrict to shuttle-execution suite
weave eval run --agent shuttle

# Restrict to spindle-tools suite
weave eval run --agent spindle

# Restrict to pattern-planning suite
weave eval run --agent pattern

# Restrict to weft-review suite
weave eval run --agent weft

# Restrict to warp-security suite
weave eval run --agent warp

# Restrict to one model (exact match)
weave eval run --model anthropic/claude-sonnet-4.5

# Restrict to one case ID (exact match)
weave eval run --case loom-route-backend-api

# Restrict to one shuttle-execution case
weave eval run --case shuttle-execution-report-structured-evidence

# Restrict to one weft-review case
weave eval run --case weft-review-clean-approval

# Restrict to one warp-security case
weave eval run --case warp-security-block-evidence-findings

# Print what would run, no execution
weave eval run --dry-run

# Emit raw prompt text locally (NEVER in CI)
weave eval run --raw-artifacts

Eval run started

  Run ID:     abc1234-2026-08-27-001
  Suites:     8
  Models:     3
  Cases:      24

Running loom-routing...
  ✓ loom-route-backend-api (anthropic/claude-sonnet-4.5)
  ✓ loom-route-frontend-ui (anthropic/claude-sonnet-4.5)
  ✓ loom-route-ambiguous-direct-shuttle (anthropic/claude-sonnet-4.5)

[...]

Eval run complete

  Run ID:     abc1234-2026-08-27-001
  Duration:   2m 34s
  Pass rate:  92% (66/72 cases)

Artifacts written to: eval-bundles/runs/abc1234-2026-08-27-001/

Dry-run prints filters and confirms no execution will occur. No model calls are made, no artifacts are written, and secrets are not required. Dry-run still performs the same input validation and suite fixture/rubric loading path as a live run.

weave eval run --agent loom --model anthropic/claude-sonnet-4.5 --dry-run

This is the recommended contributor preflight path because it exercises the same filter and suite-validation path without requiring secrets.

Security warning: --raw-artifacts is rejected in CI environments (CI=true). Passing it in a CI workflow step is a hard validation error. Raw artifacts contain composed prompt text and full transcripts and must never be committed or published.

When enabled locally, raw artifacts are written to eval-bundles/runs/<runId>/raw/. Filename components are sanitized before write, and the resolved path must stay under raw/. Add this directory to .gitignore. Raw files must never be committed to any repository.

Completed eval runs exit with code 0 even when one or more cases miss their pass threshold. Threshold misses are captured in run-summary.json and per-suite score files. The command exits non-zero for hard orchestration failures such as invalid input, missing secrets, model matrix/load failures, bundle write/publish failures, or suite-level partial failures that prevent complete results.

Detection is side-effect free. It may probe config paths, check readability, inspect PATH binaries, and read optional version strings through injected probes, but it must not create directories, write files, edit config, or launch harness runtimes.

Supported detection IDs:

• opencode
• claude-code
• pi

Installer support is intentionally separate from detection support. OpenCode has a first installer boundary; Claude Code and Pi currently report unsupported installer messages until adapter-specific installers exist.

weave init --harness opencode --yes
weave init --harness pi --yes        # explicit unsupported/undetected failure until supported
weave init --all-harnesses --yes     # install supported detected harnesses, skip unsupported ones

Harness writes only happen after explicit non-interactive flags or interactive confirmation.

Never do any of the following:

• Commit or log OPENROUTER_API_KEY values.
• Commit or log EVAL_RESULTS_REPO_TOKEN values.
• Use --raw-artifacts in any CI workflow step.
• Commit files from eval-bundles/runs/<runId>/raw/ or any file containing composedPrompt or rawContent.
• Pass raw artifacts to ArtifactBundleWriter - all publishable output must go through sanitizer.ts.