CLI Reference

Wave CLI commands for pipeline orchestration.

Quick Reference

Command	Purpose
`wave init`	Initialize a new project
`wave run`	Execute a pipeline
`wave do`	Run an ad-hoc task
`wave status`	Check pipeline status
`wave logs`	View execution logs
`wave cancel`	Cancel running pipeline
`wave artifacts`	List and export artifacts
`wave list`	List adapters, runs, pipelines, personas, contracts
`wave validate`	Validate configuration
`wave clean`	Clean up workspaces
`wave serve`	Start the web dashboard server
`wave migrate`	Database migrations

wave init

Initialize a new Wave project.

bash

wave init

Output:

Created wave.yaml
Created .wave/personas/navigator.md
Created .wave/personas/craftsman.md
Created .wave/personas/summarizer.md
Created .wave/pipelines/default.yaml

Project initialized. Run 'wave validate' to check configuration.

Options

bash

wave init --adapter opencode    # Use different adapter
wave init --force               # Overwrite existing files
wave init --merge               # Merge into existing config
wave init --workspace ./ws      # Custom workspace directory path
wave init --output config.yaml  # Custom output path for wave.yaml
wave init -y                    # Answer yes to all confirmation prompts

wave run

Execute a pipeline. Arguments can be provided as positional args or flags.

bash

# Positional arguments (recommended for quick usage)
wave run gh-pr-review "Review auth module"

# Flag-based (explicit)
wave run --pipeline gh-pr-review --input "Review auth module"

# Mixed
wave run gh-pr-review --input "Review auth module"

Output:

[run-abc123] Starting pipeline: gh-pr-review
[run-abc123] Step: analyze (navigator) - started
[run-abc123] Step: analyze (navigator) - completed (45s)
[run-abc123] Step: review (auditor) - started
[run-abc123] Step: review (auditor) - completed (1m12s)
[run-abc123] Pipeline completed in 1m57s

Options

bash

wave run hotfix --dry-run                      # Preview without executing
wave run speckit-flow --from-step implement    # Start from step (auto-recovers input)
wave run speckit-flow --from-step implement --force  # Skip validation for --from-step
wave run recinq --from-step report --run recinq-20260219-fa19  # Recover input from specific run
wave run migrate --timeout 60                  # Custom timeout (minutes)
wave run test --mock                           # Use mock adapter for testing
wave run build -o json                         # NDJSON output to stdout (pipe-friendly)
wave run deploy -o text                        # Plain text progress to stderr
wave run review -o text -v                     # Plain text with real-time tool activity
wave run check -o quiet                        # Only final result to stderr

wave do

Run an ad-hoc task without a pipeline file.

bash

wave do "fix the typo in README.md"

Output:

[run-xyz789] Generated 2-step pipeline: navigate -> execute
[run-xyz789] Step: navigate (navigator) - started
[run-xyz789] Step: navigate (navigator) - completed (23s)
[run-xyz789] Step: execute (craftsman) - started
[run-xyz789] Step: execute (craftsman) - completed (1m05s)
[run-xyz789] Task completed in 1m28s

Options

bash

wave do "audit auth" --persona auditor         # Use specific persona
wave do "test" --dry-run                       # Preview only
wave do "deploy" --mock                        # Use mock adapter for testing

wave meta

Generate and execute a custom multi-step pipeline dynamically using the philosopher persona.

bash

wave meta "implement user authentication"

Output:

Invoking philosopher to generate pipeline...
This may take a moment while the AI designs your pipeline.

Generated pipeline: implement-auth
Steps:
  1. navigate [navigator]
  2. specify [philosopher]
  3. implement [craftsman]
  4. review [auditor]

Meta pipeline completed (3m28s)
  Total steps: 4, Total tokens: 45k

Options

bash

wave meta "build API" --save api-pipeline.yaml  # Save generated pipeline
wave meta "refactor code" --dry-run             # Preview without executing
wave meta "add tests" --mock                    # Use mock adapter for testing

wave status

Check pipeline run status.

bash

wave status

Output:

RUN_ID          PIPELINE      STATUS     STEP        ELAPSED    TOKENS
run-abc123      gh-pr-review   running    review      2m15s      12k
run-xyz789      hotfix        completed  -           5m23s      28k

Detailed Status

bash

wave status run-abc123

Output:

Run ID:     run-abc123
Pipeline:   gh-pr-review
Status:     running
Step:       review
Started:    2026-02-03 14:30:22
Elapsed:    2m15s
Input:      Review auth module

Steps:
  analyze   completed   45s
  review    running     1m30s

Options

bash

wave status --all                # Show all recent runs
wave status --format json        # JSON output for scripting

wave logs

View execution logs.

bash

wave logs run-abc123

Output:

[14:30:22] started    analyze (navigator) Starting analysis
[14:31:07] completed  analyze (navigator) 45.0s 2.1k tokens Found 5 relevant files
[14:31:08] started    review (auditor) Beginning review
[14:32:20] completed  review (auditor) 72.0s 1.5k tokens Checking security patterns

Options

bash

wave logs --step analyze         # Filter by step
wave logs --errors               # Show only errors
wave logs --tail 20              # Last 20 entries
wave logs --follow               # Stream in real-time
wave logs --since 10m            # Last 10 minutes
wave logs --level error          # Log level filter (all, info, error)
wave logs --format json          # Output as JSON for scripting

wave cancel

Cancel a running pipeline.

bash

wave cancel run-abc123

Output:

Cancellation requested for run-abc123 (gh-pr-review)
Pipeline will stop after current step completes.

Force Cancel

bash

wave cancel run-abc123 --force
wave cancel run-abc123 -f              # Short flag for --force

Output:

Force cancellation sent to run-abc123 (gh-pr-review)
Process terminated.

wave artifacts

List and export artifacts.

bash

wave artifacts run-abc123

Output:

STEP      ARTIFACT        TYPE    SIZE      PATH
analyze   analysis.json   json    2.1 KB    .wave/workspaces/.../analysis.json
review    findings.md     md      4.5 KB    .wave/workspaces/.../findings.md

Export Artifacts

bash

wave artifacts run-abc123 --export ./output

Output:

Exported 2 artifacts to ./output/
  ./output/analyze/analysis.json
  ./output/review/findings.md

Options

bash

wave artifacts --step analyze    # Filter by step
wave artifacts --format json     # JSON output

wave list

List Wave configuration, resources, and execution history.

bash

wave list                  # Show all categories
wave list adapters         # List configured adapters
wave list runs             # List recent pipeline runs
wave list pipelines        # List available pipelines
wave list personas         # List configured personas
wave list contracts        # List contract schemas

Adapters

bash

wave list adapters

Output:

Adapters
────────────────────────────────────────────────────────────

  ✓ claude
    binary: claude • mode: headless • format: json

Runs

bash

wave list runs

Output:

Recent Pipeline Runs
────────────────────────────────────────────────────────────────────────────────
  RUN_ID                    PIPELINE          STATUS        STARTED             DURATION
  run-abc123                gh-pr-review       completed     2026-02-03 14:30    5m23s
  run-xyz789                hotfix            failed        2026-02-03 09:30    2m15s

Pipelines

bash

wave list pipelines

Output:

Pipelines
────────────────────────────────────────────────────────────

  gh-pr-review [4 steps]
    Automated code review workflow
    ○ analyze → review → report → notify

  speckit-flow [5 steps]
    Feature development pipeline
    ○ navigate → specify → plan → implement → validate

Personas

bash

wave list personas

Output:

Personas
────────────────────────────────────────────────────────────

  navigator
    adapter: claude • temp: 0.1 • allow:3
    Read-only codebase exploration

  craftsman
    adapter: claude • temp: 0.7 • allow:5
    Implementation and testing

Contracts

bash

wave list contracts

Output:

Contracts
────────────────────────────────────────────────────────────

  navigation [json-schema]
    used by:
      • speckit-flow → navigate (navigator)

  specification [json-schema]
    used by:
      • speckit-flow → specify (philosopher)

  validation-report [json-schema]
    (unused)

Options

bash

wave list runs --run-status failed       # Filter by status
wave list runs --limit 20                # Show more runs
wave list runs --run-pipeline hotfix     # Filter by pipeline
wave list --format json                  # JSON output

wave validate

Validate configuration.

bash

wave validate

Output (success):

Validating wave.yaml...
  Adapters: 1 defined
  Personas: 5 defined
  Pipelines: 3 discovered

All validation checks passed.

Output (errors):

Validating wave.yaml...
ERROR: Persona 'craftsman' references undefined adapter 'opencode'
ERROR: System prompt file not found: .wave/personas/missing.md

Validation failed with 2 errors.

Options

bash

wave validate -v                     # Show all checks (global --verbose flag)
wave validate --pipeline hotfix.yaml # Validate specific pipeline

wave clean

Clean up workspaces.

bash

wave clean --dry-run

Output:

Would delete:
  .wave/workspaces/run-abc123/  (gh-pr-review, 145 MB)
  .wave/workspaces/run-xyz789/  (hotfix, 23 MB)
Total: 168 MB across 2 runs

Run without --dry-run to delete.

Options

bash

wave clean --all                     # Clean all workspaces
wave clean --older-than 7d           # Clean runs older than 7 days
wave clean --status completed        # Clean only completed runs
wave clean --keep-last 5             # Keep 5 most recent
wave clean --force                   # Skip confirmation
wave clean --dry-run                 # Preview what would be deleted
wave clean --quiet                   # Suppress output for scripting

wave serve

Start the web dashboard server. Provides real-time pipeline monitoring, execution control, DAG visualization, and artifact browsing through a web interface.

Note: wave serve requires the webui build tag. Install with go install -tags webui or use a release binary that includes the web UI.

bash

wave serve

Output:

Starting Wave dashboard on http://127.0.0.1:8080

Options

Flag	Default	Description
`--port`	`8080`	Port to listen on
`--bind`	`127.0.0.1`	Address to bind to
`--token`	`""`	Authentication token (required for non-localhost binding)
`--db`	`.wave/state.db`	Path to state database
`--manifest`	`wave.yaml`	Path to manifest file

Authentication

When binding to a non-localhost address (--bind 0.0.0.0), authentication is required. The token can be provided via:

--token flag
WAVE_SERVE_TOKEN environment variable
Auto-generated (printed to stderr on startup)

bash

# Local development (no auth required)
wave serve

# Custom port
wave serve --port 9090

# Expose on all interfaces with explicit token
wave serve --bind 0.0.0.0 --token mysecret

# Use custom database path
wave serve --db .wave/state.db

wave migrate

Database migration commands.

bash

wave migrate status

Output:

Current version: 3
Available migrations: 5
Pending: 2

  v1  core_tables      applied   2026-01-15 10:00:00
  v2  add_artifacts    applied   2026-01-20 14:30:00
  v3  add_metrics      applied   2026-02-01 09:00:00
  v4  add_checkpoints  pending
  v5  add_relay        pending

Apply Migrations

bash

wave migrate up

Output:

Applying migration v4: add_checkpoints... done
Applying migration v5: add_relay... done

Migrations complete. Current version: 5

Rollback

bash

wave migrate down 3

Output:

Rolling back to version 3...
  Reverting v5: add_relay... done
  Reverting v4: add_checkpoints... done

Rollback complete. Current version: 3

Global Options

All commands support:

Flag	Short	Description
`--help`	`-h`	Show help
`--version`		Show version
`--manifest`	`-m`	Path to manifest file (default: wave.yaml)
`--debug`	`-d`	Enable debug mode
`--output`	`-o`	Output format: auto, json, text, quiet (default: auto)
`--verbose`	`-v`	Include real-time tool activity

Exit Codes

Code	Meaning
0	Success
1	General error
2	Usage error
3	Pipeline failed
4	Validation error
5	Timeout
130	Interrupted (Ctrl+C)

Next Steps

Quickstart - Run your first pipeline
Pipelines - Define multi-step workflows
Manifest Reference - Configuration options

CLI Reference ​

Quick Reference ​

wave init ​

Options ​

wave run ​

Options ​

wave do ​

Options ​

wave meta ​

Options ​

wave status ​

Detailed Status ​

Options ​

wave logs ​

Options ​

wave cancel ​

Force Cancel ​

wave artifacts ​

Export Artifacts ​

Options ​

wave list ​

Adapters ​

Runs ​

Pipelines ​

Personas ​

Contracts ​

Options ​

wave validate ​

Options ​

wave clean ​

Options ​

wave serve ​

Options ​

Authentication ​

wave migrate ​

Apply Migrations ​

Rollback ​

Global Options ​

Exit Codes ​

Next Steps ​

CLI Reference

Quick Reference

wave init

Options

wave run

Options

wave do

Options

wave meta

Options

wave status

Detailed Status

Options

wave logs

Options

wave cancel

Force Cancel

wave artifacts

Export Artifacts

Options

wave list

Adapters

Runs

Pipelines

Personas

Contracts

Options

wave validate

Options

wave clean

Options

wave serve

Options

Authentication

wave migrate

Apply Migrations

Rollback

Global Options

Exit Codes

Next Steps