Skip to content

CLI.md

Latest commit

 

History

History
779 lines (542 loc) · 14.5 KB

CLI.md

File metadata and controls

779 lines (542 loc) · 14.5 KB
Raw

CodeWave CLI Documentation

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

Code Meaning Solution
0 Success No action needed
1 General failure Check error message
2 Invalid arguments Verify syntax with --help
3 Commit not found Check commit hash/reference
4 Configuration error Run codewave config
5 API authentication failed Verify API key with codewave config show
6 Rate limit exceeded Reduce parallelization
7 Network error Check internet connection
8 File system error Check 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: