CLI Commands

CLI Commands

Reference documentation for the Stepwright and Fixwright command line interfaces.

Stepwright CLI

Installation

The CLI is included with the @korvol/stepwright package:

npm install @korvol/stepwright

Commands

stepwright run

Run a Stepwright script.

npx stepwright run <script> [options]

Arguments:

Argument	Description
<script>	Path to the script file (.ts or .js)

Options:

Option	Description	Default
--headed	Run with visible browser	false
--headless	Run without visible browser	true
--browser <type>	Browser to use (chromium, firefox, webkit)	chromium
--timeout <ms>	Default timeout in milliseconds	30000
--json <path>	Output results as JSON to file	-
--video	Record video of execution	false
--video-dir <path>	Directory for video output	.stepwright/videos
--screenshots	Take screenshot after each step	false
--verbose	Enable verbose logging	false
--config <path>	Path to config file	-
-h, --help	Show help	-

Examples:

# Basic run
npx stepwright run ./scripts/checkout.ts

# Run with visible browser
npx stepwright run ./scripts/checkout.ts --headed

# Run on Firefox
npx stepwright run ./scripts/checkout.ts --browser firefox

# Save results to JSON
npx stepwright run ./scripts/checkout.ts --json ./results.json

# Record video
npx stepwright run ./scripts/checkout.ts --video --video-dir ./recordings

# Verbose output
npx stepwright run ./scripts/checkout.ts --verbose

stepwright list

List available scripts in a directory.

npx stepwright list [directory] [options]

Arguments:

Argument	Description
[directory]	Directory to scan (default: current directory)

Options:

Option	Description
--recursive	Search subdirectories
--json	Output as JSON

Examples:

# List scripts in current directory
npx stepwright list

# List scripts in specific directory
npx stepwright list ./scripts

# List recursively
npx stepwright list ./scripts --recursive

# Output as JSON
npx stepwright list --json

stepwright init

Initialize a new Stepwright project.

npx stepwright init [directory] [options]

Options:

Option	Description
--typescript	Use TypeScript (default)
--javascript	Use JavaScript
--force	Overwrite existing files

Examples:

# Initialize in current directory
npx stepwright init

# Initialize in new directory
npx stepwright init my-automation

# Initialize with JavaScript
npx stepwright init --javascript

stepwright validate

Validate script syntax without running.

npx stepwright validate <script>

Examples:

# Validate a script
npx stepwright validate ./scripts/checkout.ts

# Validate multiple scripts
npx stepwright validate ./scripts/*.ts

---

Fixwright CLI

Installation

The CLI is included with the @korvol/fixwright package:

npm install @korvol/fixwright

Commands

fixwright fix

Fix a failing script.

npx fixwright fix <failure-case> [options]

Arguments:

Argument	Description
<failure-case>	Path to failure case JSON file

Options:

Option	Description	Default
--api-key <key>	Anthropic API key	$ANTHROPIC_API_KEY
--model <model>	Claude model to use	claude-sonnet-4-20250514
--max-attempts <n>	Maximum fix attempts	3
--dry-run	Show fix without applying	false
--backup	Create backup before fixing	true
--no-backup	Skip backup creation	-
--git	Enable Git integration	false
--create-pr	Create PR after fixing	false
--verbose	Verbose output	false
-h, --help	Show help	-

Examples:

# Basic fix
npx fixwright fix ./failure-cases/checkout-failure.json

# Dry run (preview fix)
npx fixwright fix ./failure-cases/failure.json --dry-run

# With Git integration
npx fixwright fix ./failure-cases/failure.json --git

# Create PR
npx fixwright fix ./failure-cases/failure.json --git --create-pr

# Custom model
npx fixwright fix ./failure-cases/failure.json --model claude-sonnet-4-20250514

# Multiple attempts
npx fixwright fix ./failure-cases/failure.json --max-attempts 5

fixwright watch

Watch for failures and fix automatically.

npx fixwright watch <directory> [options]

Arguments:

Argument	Description
<directory>	Directory to watch for failure cases

Options:

Option	Description	Default
--api-key <key>	Anthropic API key	$ANTHROPIC_API_KEY
--pattern <glob>	File pattern to watch	*.json
--debounce <ms>	Debounce time	1000

Examples:

# Watch for failures
npx fixwright watch ./failure-cases

# Custom pattern
npx fixwright watch ./failures --pattern "*.failure.json"

fixwright generate-case

Generate a failure case from a script result.

npx fixwright generate-case <result-json> [options]

Arguments:

Argument	Description
<result-json>	Path to Stepwright result JSON

Options:

Option	Description	Default
-o, --output <path>	Output path for failure case	-
--script-path <path>	Path to the original script	-

Examples:

# Generate from result
npx fixwright generate-case ./results.json -o ./failure-cases/

# With script path
npx fixwright generate-case ./results.json --script-path ./scripts/checkout.ts

---

Global Options

These options work with both CLIs:

Option	Description
--version	Show version number
--help	Show help
--no-color	Disable colored output
--quiet	Suppress non-essential output

---

Exit Codes

Both CLIs use standard exit codes:

Code	Meaning
0	Success
1	Script/fix failed
2	Syntax/configuration error
3	File not found
130	User interrupt (Ctrl+C)

Using in scripts:

#!/bin/bash
npx stepwright run ./scripts/main.ts

if [ $? -eq 0 ]; then
  echo "Success!"
elif [ $? -eq 1 ]; then
  echo "Script failed, generating failure case..."
  npx fixwright generate-case ./results.json
else
  echo "Error occurred"
fi

---

Shell Completion

Bash

# Add to ~/.bashrc
eval "$(npx stepwright completion bash)"

Zsh

# Add to ~/.zshrc
eval "$(npx stepwright completion zsh)"

Fish

# Add to ~/.config/fish/config.fish
npx stepwright completion fish | source

---

Configuration File

Both CLIs can use configuration files:

stepwright.config.ts

export default {
  headless: true,
  browser: 'chromium',
  timeout: 30000,
  screenshotOnFailure: true,
};

fixwright.config.ts

export default {
  ai: {
    apiKey: process.env.ANTHROPIC_API_KEY,
    model: 'claude-sonnet-4-20250514',
  },
  maxAttempts: 3,
  git: {
    enabled: true,
  },
};

Use with --config:

npx stepwright run ./script.ts --config ./custom-config.ts
npx fixwright fix ./failure.json --config ./fixwright.config.ts

Tip

Configuration files are automatically loaded from the current directory if named stepwright.config.ts or fixwright.config.ts.

Next Steps

• Environment Variables - Environment configuration
• Configuration Reference - All config options