CLI Options

Comprehensive reference for all command-line options available in curl-runner, including examples and best practices.

Copy Markdown

curl-runner provides numerous CLI options to customize execution behavior, output formatting, and error handling. Options can be combined and have both short and long forms.

Option Syntax

Understanding curl-runner option formats

• Short options: -v -p -c (can be combined as -vpc)
• Long options: --verbose --parallel
• Options with values: --timeout 5000

Available Options

Options are grouped by functionality for easier reference.

Help & Information

-h--help

Display help information with usage examples and exit.

booleandefault: false
Example:
curl-runner --help
--version

Show the curl-runner version number and exit.

booleandefault: false
Example:
curl-runner --version

Execution Control

-p--execution parallel

Set execution mode. Options: 'sequential' (default) or 'parallel'.

stringdefault: sequential
Example:
curl-runner tests/ --execution parallel
-c--continue-on-error

Continue executing remaining requests even if some fail.

booleandefault: false
Example:
curl-runner tests/ --continue-on-error
--timeout <milliseconds>

Set global timeout for all requests in milliseconds.

numberdefault: 5000
Example:
curl-runner tests/ --timeout 10000
--retries <count>

Maximum number of retries for failed requests.

numberdefault: 0
Example:
curl-runner tests/ --retries 3
--retry-delay <milliseconds>

Delay between retry attempts in milliseconds.

numberdefault: 1000
Example:
curl-runner tests/ --retries 3 --retry-delay 2000
--no-retry

Disable retry mechanism completely.

booleandefault: false
Example:
curl-runner tests/ --no-retry
-n--dry-run

Show curl commands without executing them. Useful for previewing and debugging.

booleandefault: false
Example:
curl-runner api.yaml --dry-run
--http2

Use HTTP/2 protocol with multiplexing for improved performance.

booleandefault: false
Example:
curl-runner api.yaml --http2
-e--env <name>

Select environment to load .env.{name} files. Enables environment-specific variable overrides.

stringdefault: none
Example:
curl-runner api.yaml --env production
--no-redact

Disable automatic secret redaction in output. Not recommended for shared terminals.

booleandefault: false
Example:
curl-runner api.yaml --no-redact

File Discovery

--all

Recursively search for YAML files in directories.

booleandefault: false
Example:
curl-runner tests/ --all

Output Control

-v--verbose

Enable verbose output with detailed request/response information.

booleandefault: false
Example:
curl-runner tests/ --verbose
--output <file>

Save execution results to a JSON file.

stringdefault: none
Example:
curl-runner tests/ --output results.json
--quiet

Suppress all output except errors (opposite of --verbose).

booleandefault: false
Example:
curl-runner tests/ --quiet
--output-format <format>

Set output format. Options: 'json', 'pretty', or 'raw'.

stringdefault: pretty
Example:
curl-runner tests/ --output-format json
--pretty-level <level>

Set pretty format detail level. Options: 'minimal', 'standard', or 'detailed'.

stringdefault: standard
Example:
curl-runner tests/ --pretty-level detailed
--show-headers

Include response headers in output.

booleandefault: false
Example:
curl-runner tests/ --show-headers
--show-body

Include response body in output.

booleandefault: false
Example:
curl-runner tests/ --show-body
--show-metrics

Include performance metrics in output.

booleandefault: false
Example:
curl-runner tests/ --show-metrics

Watch Mode

-w--watch

Watch files for changes and automatically re-run requests when files are modified.

booleandefault: false
Example:
curl-runner api.yaml --watch
--watch-debounce <milliseconds>

Debounce delay for watch mode. Prevents rapid re-runs when files change quickly.

numberdefault: 300
Example:
curl-runner tests/ -w --watch-debounce 500
--no-watch-clear

Disable screen clearing between watch mode runs.

booleandefault: false
Example:
curl-runner api.yaml -w --no-watch-clear

Combining Options

Short options can be combined, and multiple options can be used together for powerful configurations.

Option Combinations
# Basic combinations
curl-runner tests/ -v                    # Verbose output
curl-runner tests/ -p                    # Parallel execution
curl-runner tests/ -c                    # Continue on error
curl-runner tests/ -n                    # Dry run (preview commands)
curl-runner tests/ -pv                   # Parallel + verbose
curl-runner tests/ -pc                   # Parallel + continue on error
curl-runner tests/ -pvc                  # Parallel + verbose + continue on error

# With long options
curl-runner tests/ --execution parallel --verbose --continue-on-error

# Output format combinations
curl-runner tests/ --output-format json --show-metrics
curl-runner tests/ --output-format pretty --pretty-level detailed
curl-runner tests/ --show-headers --show-body --show-metrics

# Advanced combinations
curl-runner tests/ \
  --execution parallel \
  --continue-on-error \
  --output-format pretty \
  --pretty-level detailed \
  --show-headers \
  --show-metrics \
  --timeout 30000 \
  --retries 3 \
  --retry-delay 2000 \
  --output results.json \
  --all

# Retry configurations
curl-runner tests/ --retries 5 --retry-delay 1500  # Custom retry settings
curl-runner tests/ --no-retry                      # Disable retries completely

# Watch mode
curl-runner api.yaml -w                            # Watch and re-run on changes
curl-runner tests/ --watch --watch-debounce 500    # Custom debounce delay
curl-runner api.yaml -w --no-watch-clear           # Don't clear screen between runs
curl-runner tests/ -wpv                            # Watch + parallel + verbose

Environment Variables

Many CLI options can be set via environment variables, which take precedence over default values but are overridden by explicit CLI options.

Supported Environment Variables

Execution Options

CURL_RUNNER_EXECUTIONexecution mode (sequential/parallel)
CURL_RUNNER_CONTINUE_ON_ERRORcontinue on error (true/false)
CURL_RUNNER_TIMEOUTglobal timeout in milliseconds
CURL_RUNNER_RETRIESmaximum retry attempts
CURL_RUNNER_DRY_RUNdry run mode (true/false)

Output Options

CURL_RUNNER_VERBOSEenable verbose output (true/false)
CURL_RUNNER_OUTPUToutput file path
CURL_RUNNER_QUIETsuppress output (true/false)
Environment Variable Examples
# Environment variables override CLI options
CURL_RUNNER_TIMEOUT=10000 curl-runner tests/
CURL_RUNNER_RETRIES=3 curl-runner tests/
CURL_RUNNER_RETRY_DELAY=2000 curl-runner tests/
CURL_RUNNER_VERBOSE=true curl-runner tests/
CURL_RUNNER_EXECUTION=parallel curl-runner tests/
CURL_RUNNER_CONTINUE_ON_ERROR=true curl-runner tests/
CURL_RUNNER_DRY_RUN=true curl-runner tests/

# Output format environment variables
CURL_RUNNER_OUTPUT_FORMAT=json curl-runner tests/
CURL_RUNNER_PRETTY_LEVEL=detailed curl-runner tests/
CURL_RUNNER_OUTPUT_FILE=results.json curl-runner tests/

# Watch mode environment variables
CURL_RUNNER_WATCH=true curl-runner api.yaml
CURL_RUNNER_WATCH_DEBOUNCE=500 curl-runner tests/ -w
CURL_RUNNER_WATCH_CLEAR=false curl-runner api.yaml -w

# Multiple environment variables
CURL_RUNNER_TIMEOUT=15000 \
CURL_RUNNER_RETRIES=2 \
CURL_RUNNER_RETRY_DELAY=1500 \
CURL_RUNNER_VERBOSE=true \
CURL_RUNNER_OUTPUT_FORMAT=pretty \
CURL_RUNNER_PRETTY_LEVEL=detailed \
curl-runner tests/ --execution parallel

# Mix environment variables and CLI options
CURL_RUNNER_TIMEOUT=10000 \
CURL_RUNNER_OUTPUT_FORMAT=json \
curl-runner tests/ --verbose --show-metrics --output results.json

Configuration File

Create a curl-runner.yaml file in your project root to set default options.

curl-runner.yaml
# curl-runner.yaml (configuration file)
global:
  execution: parallel
  continueOnError: true
  output:
    verbose: false
    format: pretty
    prettyLevel: detailed
    showHeaders: true
    showBody: true
    showMetrics: true
    saveToFile: results.json
  defaults:
    timeout: 10000
    retry:
      count: 2
      delay: 1000
  variables:
    API_BASE: "https://api.example.com"
    API_VERSION: "v2"

# CLI options override config file settings
curl-runner tests/ --verbose --pretty-level minimal  # Overrides config file settings

Output Format

When using --output, results are saved in structured JSON format.

results.json
# JSON output format (when using --output)
{
  "summary": {
    "total": 10,
    "successful": 8,
    "failed": 2,
    "duration": 2345
  },
  "requests": [
    {
      "name": "Get Users",
      "status": "success",
      "statusCode": 200,
      "duration": 234,
      "url": "https://api.example.com/users"
    },
    {
      "name": "Invalid Request", 
      "status": "failed",
      "error": "Request timeout after 5000ms",
      "url": "https://slow-api.example.com/endpoint"
    }
  ]
}

Option Precedence

When options are specified in multiple ways, curl-runner follows this precedence order:

1

CLI Options

Command-line flags take highest precedence

--verbose --timeout 5000
2

Environment Variables

Override defaults but yield to CLI flags

CURL_RUNNER_VERBOSE=true
3

Configuration File

Project-specific defaults from curl-runner.yaml

curl-runner.yaml
4

Built-in Defaults

Fallback values when nothing else is specified

sequential, timeout: 5000

Best Practices

Recommended Practices

Best practices for optimal usage

• Use configuration files for team consistency
• Use --verbose during development
• Set appropriate timeouts for your APIs
• Use --continue-on-error for test suites
• Save results with --output for analysis

Important Cautions

Things to be mindful of when using options

• Parallel execution may overwhelm servers
• High retry counts can cause rate limiting
• Very low timeouts may cause false failures
• Verbose output can be overwhelming for large test suites
• Environment variables affect all executions