CodeWave CLI Documentation

November 27, 2025 · View on GitHub

Complete command-line interface reference with examples for every command and option.

Table of Contents

  1. Global Options
  2. evaluate Command
  3. batch-evaluate Command
  4. generate-okr Command
  5. config Command
  6. Exit Codes
  7. Examples

Global Options

These options work with all commands:

codewave [command] [options]

--help / -h

Display help information.

codewave --help              # General help
codewave evaluate --help     # Command-specific help

--version / -V

Display CodeWave version.

codewave --version
# Output: 1.0.0

evaluate Command

Evaluate a single commit with comprehensive multi-agent analysis.

Syntax

codewave evaluate <commit-hash> [options]

Arguments

<commit-hash> (Required)

Git commit reference to evaluate. Can be:

  • Commit hash: abc1234, abc1234567890
  • Reference: HEAD, main, develop
  • Branch name: feature/auth-system
  • Tag: v1.2.3
  • Relative: HEAD~1, HEAD~5

Examples:

codewave evaluate HEAD                    # Latest commit
codewave evaluate abc1234                 # Specific commit
codewave evaluate feature/new-feature     # Latest on branch
codewave evaluate HEAD~1                  # Previous commit

Options

-o, --output <directory>

Output directory for evaluation results.

Type: String (file path) Default: .evaluated-commits

codewave evaluate HEAD -o ./reports
codewave evaluate HEAD --output ./my-analysis

--repo <path>

Path to Git repository.

Type: String (file path) Default: Current directory

codewave evaluate HEAD --repo /path/to/repo

-f, --format <format>

Output format(s).

Type: json, html, markdown, all Default: all

codewave evaluate HEAD --format json        # JSON only
codewave evaluate HEAD -f html              # HTML only
codewave evaluate HEAD --format markdown    # Markdown only
codewave evaluate HEAD -f all               # All formats

--verbose

Enable verbose logging.

Type: Boolean flag Default: false

codewave evaluate HEAD --verbose

Verbose Output Includes:

  • Agent prompts and reasoning
  • Token counts per API call
  • Timing for each stage
  • Full LLM responses
  • Error details

--no-report

Skip HTML report generation.

Type: Boolean flag Default: false

codewave evaluate HEAD --no-report      # Generate only JSON/text

Useful when:

  • Running in headless environments
  • Generating only for CI/CD
  • Large batch processing (faster)

--model <model>

Override configured LLM model.

Type: String (model ID) Default: Configured value

codewave evaluate HEAD --model claude-3-opus-20250219
codewave evaluate HEAD --model gpt-4o

Common Models:

  • claude-3-5-sonnet-20241022 (Anthropic, recommended)
  • claude-3-opus-20250219 (Anthropic, best quality)
  • claude-3-haiku-20240307 (Anthropic, fastest)
  • gpt-4o (OpenAI)
  • gpt-4-turbo (OpenAI)
  • gemini-2.0-flash (Google)

Output Format

✓ Evaluation completed in 2.3s

Results saved to: .evaluated-commits/abc1234_2024-01-15_10-30-45/

Files:
  • report.html      - Interactive HTML report
  • results.json     - Structured results
  • commit.diff      - Original diff
  • summary.txt      - Text summary

Metrics:
  Code Quality:      8.5 / 10
  Complexity:        7.0 / 10
  Test Coverage:     8.0 / 10
  Overall Score:     8.1 / 10

Next: Open report.html in your browser to view conversation timeline

Exit Code

  • 0: Success
  • 1: Evaluation failed
  • 2: Invalid arguments
  • 3: Commit not found
  • 4: Configuration error

batch-evaluate Command

Evaluate multiple commits with progress tracking.

Syntax

codewave batch-evaluate [options]

Options

--count <number>

Number of commits to evaluate.

Type: Positive integer Default: 10 Max: 1000

codewave batch-evaluate --count 5        # Last 5 commits
codewave batch-evaluate --count 100      # Last 100 commits

--since <date>

Start date for commit range.

Type: ISO date string or natural language Default: null (no start limit)

Formats:

# ISO format
codewave batch-evaluate --since 2024-01-01

# Natural language
codewave batch-evaluate --since "2 weeks ago"
codewave batch-evaluate --since "January 1, 2024"

# With end date
codewave batch-evaluate --since 2024-01-01 --until 2024-01-31

--until <date>

End date for commit range.

Type: ISO date string or natural language Default: null (current date)

codewave batch-evaluate --until 2024-12-31
codewave batch-evaluate --until "today"

--branch <branch-name>

Branch to evaluate commits from.

Type: String (branch name) Default: Current branch

codewave batch-evaluate --branch main      # Commits on main
codewave batch-evaluate --branch develop   # Commits on develop

-o, --output <directory>

Output directory for results.

Type: String (file path) Default: .evaluated-commits

codewave batch-evaluate -o ./batch-reports

--parallel <number>

Number of parallel evaluations.

Type: Integer (1-5) Default: 3

codewave batch-evaluate --parallel 1      # Sequential (slow, low cost)
codewave batch-evaluate --parallel 3      # Balanced (default)
codewave batch-evaluate --parallel 5      # Maximum (fast, high cost)

Considerations:

  • 1: Slow but reliable, minimal rate-limit issues
  • 3: Good balance (default)
  • 5: Fast but may hit rate limits

--skip-errors

Continue processing on errors instead of halting.

Type: Boolean flag Default: false

codewave batch-evaluate --skip-errors --count 100

If a commit evaluation fails:

  • Without flag: Batch stops immediately
  • With flag: Logs error and continues

--verbose

Enable verbose logging.

Type: Boolean flag Default: false

codewave batch-evaluate --count 50 --verbose

Displays detailed information about:

  • Each commit being evaluated
  • Token usage per commit
  • Estimated costs
  • Processing times

Progress Display

During batch evaluation, real-time progress is displayed:

CodeWave - Batch Evaluation
============================

Evaluating commits...
[████████████████████░░░░░░░░░░░] 65% (65/100)

Current: abc1234 - "feat: add user auth"
Elapsed: 2m 34s | ETA: 1m 20s

Metrics:
  ✓ Successful: 65
  ✗ Failed: 0
  ⊘ Skipped: 0
  Avg Quality: 7.8 / 10
  Avg Coverage: 7.5 / 10

Performance:
  Avg Time: 2.3s / commit
  Tokens: 18,450 / 100,000
  Cost: \$0.45 / 5.00

Output Structure

.evaluated-commits/
├── abc1234_2024-01-15_10-30-45/
│   ├── report.html
│   ├── results.json
│   ├── commit.diff
│   └── summary.txt
├── def5678_2024-01-15_10-33-12/
│   ├── report.html
│   ├── results.json
│   ├── commit.diff
│   └── summary.txt
└── batch-summary.json

Batch Summary

After completion, a summary is displayed:

✓ Batch evaluation completed!

Summary:
  • Total:      100 commits
  • Successful: 100
  • Failed:     0
  • Duration:   3m 52s
  • Avg Time:   2.3s per commit

Quality:
  • Avg Quality Score:  7.8 / 10
  • Avg Complexity:     7.0 / 10
  • Avg Test Coverage:  7.5 / 10

Cost:
  • Total Tokens: 456,000
  • Estimated Cost: \$2.30

Results:
  • Output Directory: .evaluated-commits/
  • Summary Report:   batch-summary.json

generate-okr Command

Generate Objectives and Key Results (OKRs) for developers based on their commit history.

Syntax

codewave generate-okr [options]

Options

--authors <names>

Comma-separated list of author names to generate OKRs for.

Type: String Default: All authors found in evaluation data

codewave generate-okr --authors "John Doe,Jane Smith"

--months <number>

Number of months of history to analyze.

Type: Integer Default: 3

codewave generate-okr --months 6

--concurrency <number>

Number of parallel generations.

Type: Integer Default: 2

codewave generate-okr --concurrency 4

--model <model>

Override the LLM model used for generation.

Type: String

codewave generate-okr --model gpt-4o

config Command

Manage CodeWave configuration.

Syntax

codewave config [subcommand] [options]

Subcommands

Interactive Setup (Default)

codewave config

Launches interactive wizard for configuration:

  1. Choose LLM provider
  2. Enter API key
  3. Select model
  4. Configure output directory
  5. Set batch size
  6. Enable/disable RAG

show

Display current configuration.

codewave config show

Output:

CodeWave Configuration
=====================

LLM Provider:        anthropic
Model:               claude-3-5-sonnet-20241022
API Key:             sk-ant-... (masked)
Output Directory:    .evaluated-commits
Batch Size:          10
Parallel:            3
Max Tokens:          4000
Enable RAG:          true
RAG Chunk Size:      2000
Verbose:             false

set <key> <value>

Set a specific configuration value.

codewave config set <key> <value>

Common Keys:

codewave config set llm-provider anthropic
codewave config set model claude-3-5-sonnet-20241022
codewave config set api-key sk-ant-...
codewave config set output-directory ./reports
codewave config set batch-size 20
codewave config set parallel-evaluations 5
codewave config set max-tokens 6000
codewave config set enable-rag true
codewave config set verbose false

reset

Reset configuration to defaults.

codewave config reset

Warning: Removes API keys. You'll need to reconfigure.

Exit Codes

CodeMeaningSolution
0SuccessNo action needed
1General failureCheck error message
2Invalid argumentsVerify syntax with --help
3Commit not foundCheck commit hash/reference
4Configuration errorRun codewave config
5API authentication failedVerify API key with codewave config show
6Rate limit exceededReduce parallelization
7Network errorCheck internet connection
8File system errorCheck permissions on output directory

Examples

Example 1: Quick Evaluation

# Evaluate current commit
codewave evaluate HEAD

# Output appears in .evaluated-commits/
# Open report.html in browser

Example 2: Evaluate Specific Branch

# Evaluate commit on develop branch
codewave evaluate develop

# With verbose output
codewave evaluate develop --verbose

Example 3: Custom Output Location

# Save to custom directory
codewave evaluate HEAD -o ./my-reports

# Save with specific format
codewave evaluate HEAD -f json -o ./ci-reports

Example 4: Batch Evaluation - Last Week

# Commits from last 7 days
codewave batch-evaluate --since "7 days ago"

# With verbose progress
codewave batch-evaluate --since "7 days ago" --verbose

Example 5: Batch Evaluation - Date Range

# January 2024
codewave batch-evaluate \
  --since 2024-01-01 \
  --until 2024-01-31 \
  --parallel 5

# With custom output
codewave batch-evaluate \
  --since 2024-01-01 \
  --until 2024-01-31 \
  -o ./january-analysis

Example 6: Specific Branch with Limit

# Last 20 commits on develop branch
codewave batch-evaluate \
  --branch develop \
  --count 20

# With maximum parallelization
codewave batch-evaluate \
  --branch main \
  --count 100 \
  --parallel 5

Example 7: CI/CD Integration

# JSON output for programmatic access
codewave evaluate $CI_COMMIT_SHA \
  --format json \
  -o ./ci-results \
  --no-report  # Skip HTML

# Check results
cat ./ci-results/*/results.json | jq '.metrics.codeQuality'

Example 8: Error Handling in Batch

# Continue on errors
codewave batch-evaluate \
  --count 100 \
  --skip-errors \
  --verbose

# Check what failed
grep "✗" batch-summary.json

Example 9: Using Different Model

# Use cheaper model for speed
codewave evaluate HEAD --model claude-3-haiku-20240307

# Use best quality model
codewave evaluate HEAD --model claude-3-opus-20250219

# Use Google Gemini
codewave config set llm-provider google
codewave config set model gemini-2.0-flash
codewave evaluate HEAD

Example 10: Verbose Debugging

# Enable verbose mode for debugging
codewave evaluate HEAD --verbose

# See detailed output including:
# - Agent prompts
# - Token usage
# - Timing
# - Full LLM responses

Shell Completion

Bash Completion

Add to .bashrc:

complete -W "evaluate batch-evaluate config" codewave

Zsh Completion

Add to .zshrc:

compdef _gnu_generic codewave

Tips

Faster Evaluation

# Use fast model
codewave evaluate HEAD --model claude-3-haiku-20240307

# Skip HTML report generation
codewave evaluate HEAD --no-report

# Use JSON format only
codewave evaluate HEAD --format json

Better Quality

# Use best model
codewave evaluate HEAD --model claude-3-opus-20250219

# Enable verbose for debugging
codewave evaluate HEAD --verbose

Cheaper Batch Processing

# Use Google Gemini (10x cheaper)
codewave config set llm-provider google
codewave config set model gemini-2.0-flash

# Process in parallel
codewave batch-evaluate --count 1000 --parallel 5

Debugging Issues

# Show configuration
codewave config show

# Run with verbose output
codewave evaluate HEAD --verbose

# Check specific commit
codewave evaluate abc1234 --verbose

For more information: