Global Settings

Configure global execution settings, defaults, and behaviors that apply to all requests in your YAML files.

Global settings allow you to configure default behavior for all requests in a YAML file. These settings can be overridden by individual requests when needed.

basic-global-config.yaml

# Basic global configuration
global:
  # Execution settings
  execution: sequential
  continueOnError: false
  
  # Timeout settings
  timeout: 5000
  retries: 3
  
  # Output settings
  output:
    verbose: true
    saveToFile: "results.json"
    
  # Default request settings
  defaults:
    headers:
      User-Agent: "curl-runner/1.0.0"
      Accept: "application/json"
    timeout: 10000

requests:
  - name: Example Request
    url: https://api.example.com/data
    method: GET

# Basic global configuration
global:
  # Execution settings
  execution: sequential
  continueOnError: false
  
  # Timeout settings
  timeout: 5000
  retries: 3
  
  # Output settings
  output:
    verbose: true
    saveToFile: "results.json"
    
  # Default request settings
  defaults:
    headers:
      User-Agent: "curl-runner/1.0.0"
      Accept: "application/json"
    timeout: 10000

requests:
  - name: Example Request
    url: https://api.example.com/data
    method: GET

Execution Settings

Control how requests are executed and how errors are handled.

Sequential ModeDefault

Requests execute one after another in the order they appear. Useful for dependent requests or when order matters.

Parallel ModeFast

All requests execute simultaneously for maximum speed. Best for independent requests that don't depend on each other.

execution-modes.yaml

# Sequential execution (default)
global:
  execution: sequential  # Requests run one after another
  
# Parallel execution  
global:
  execution: parallel   # All requests run simultaneously
  
# With error handling
global:
  execution: parallel
  continueOnError: true  # Don't stop if some requests fail

# Sequential execution (default)
global:
  execution: sequential  # Requests run one after another
  
# Parallel execution  
global:
  execution: parallel   # All requests run simultaneously
  
# With error handling
global:
  execution: parallel
  continueOnError: true  # Don't stop if some requests fail

Timeout & Retry Settings

Configure global timeout and retry behavior for robust request handling.

Timeout

Maximum time to wait for a request to complete (milliseconds)

Retries

Number of retry attempts for failed requests

Retry Delay

Wait time between retry attempts (milliseconds)

Backoff

Exponential backoff multiplier for retry delays

timeout-retry-config.yaml

# Global timeout and retry settings
global:
  # Global timeout for all requests (milliseconds)
  timeout: 10000
  
  # Maximum retries for failed requests
  retries: 3
  
  # Retry delay settings
  retryDelay: 1000        # Initial delay between retries (ms)
  retryBackoff: 2.0       # Exponential backoff multiplier
  
  # Individual request can override these
  defaults:
    timeout: 5000         # Default per-request timeout
    retries: 1            # Default per-request retries

requests:
  - name: Standard Request
    url: https://api.example.com/data
    method: GET
    # Uses global defaults
    
  - name: Custom Timeout Request
    url: https://slow-api.example.com/data
    method: GET
    timeout: 30000        # Overrides global default
    retries: 5            # Overrides global default

# Global timeout and retry settings
global:
  # Global timeout for all requests (milliseconds)
  timeout: 10000
  
  # Maximum retries for failed requests
  retries: 3
  
  # Retry delay settings
  retryDelay: 1000        # Initial delay between retries (ms)
  retryBackoff: 2.0       # Exponential backoff multiplier
  
  # Individual request can override these
  defaults:
    timeout: 5000         # Default per-request timeout
    retries: 1            # Default per-request retries

requests:
  - name: Standard Request
    url: https://api.example.com/data
    method: GET
    # Uses global defaults
    
  - name: Custom Timeout Request
    url: https://slow-api.example.com/data
    method: GET
    timeout: 30000        # Overrides global default
    retries: 5            # Overrides global default

Output Configuration

Customize how curl-runner displays results and saves output data.

output-config.yaml

# Output configuration options
global:
  output:
    # Verbose output with request/response details
    verbose: true
    
    # Save results to JSON file
    saveToFile: "test-results.json"
    
    # Include response bodies in output
    includeResponseBody: true
    
    # Include request details in output
    includeRequestDetails: true
    
    # Format for console output
    format: "detailed"  # Options: "minimal", "standard", "detailed"
    
    # Colorize console output
    colors: true
    
    # Show progress indicators
    showProgress: true
    
    # Timestamp format
    timestampFormat: "ISO"  # Options: "ISO", "unix", "relative"

# Output configuration options
global:
  output:
    # Verbose output with request/response details
    verbose: true
    
    # Save results to JSON file
    saveToFile: "test-results.json"
    
    # Include response bodies in output
    includeResponseBody: true
    
    # Include request details in output
    includeRequestDetails: true
    
    # Format for console output
    format: "detailed"  # Options: "minimal", "standard", "detailed"
    
    # Colorize console output
    colors: true
    
    # Show progress indicators
    showProgress: true
    
    # Timestamp format
    timestampFormat: "ISO"  # Options: "ISO", "unix", "relative"

Global Defaults

Set default values that are automatically applied to all requests unless overridden.

Common Defaults

• Headers: Authentication, content types, user agents

• Timeouts: Request and connection timeouts

• Validation: Expected status codes, response times

• Query Params: API versions, formats

Override Behavior

• Individual requests can override any default

• Headers are merged (new ones added, existing ones replaced)

• Scalar values (timeout, retries) are completely replaced

• Arrays and objects are merged by default

global-defaults.yaml

# Global defaults applied to all requests
global:
  defaults:
    # Default headers for all requests
    headers:
      User-Agent: "MyApp/1.0.0"
      Accept: "application/json"
      Content-Type: "application/json"
      X-Client-Version: "1.2.3"
      
    # Default timeout and retry settings
    timeout: 8000
    retries: 2
    
    # Default validation rules
    validation:
      statusCodes: [200, 201, 202]
      maxResponseTime: 5000
      
    # Default query parameters
    query:
      api_version: "2023-01-01"
      format: "json"

requests:
  - name: Inherits All Defaults
    url: https://api.example.com/users
    method: GET
    # All global defaults are applied
    
  - name: Overrides Some Defaults
    url: https://api.example.com/posts
    method: POST
    headers:
      Content-Type: "application/xml"  # Overrides default
      # Other headers from defaults still apply
    timeout: 15000  # Overrides default timeout

# Global defaults applied to all requests
global:
  defaults:
    # Default headers for all requests
    headers:
      User-Agent: "MyApp/1.0.0"
      Accept: "application/json"
      Content-Type: "application/json"
      X-Client-Version: "1.2.3"
      
    # Default timeout and retry settings
    timeout: 8000
    retries: 2
    
    # Default validation rules
    validation:
      statusCodes: [200, 201, 202]
      maxResponseTime: 5000
      
    # Default query parameters
    query:
      api_version: "2023-01-01"
      format: "json"

requests:
  - name: Inherits All Defaults
    url: https://api.example.com/users
    method: GET
    # All global defaults are applied
    
  - name: Overrides Some Defaults
    url: https://api.example.com/posts
    method: POST
    headers:
      Content-Type: "application/xml"  # Overrides default
      # Other headers from defaults still apply
    timeout: 15000  # Overrides default timeout

Global Variables

Define reusable variables that can be referenced throughout your request configurations.

global-variables.yaml

# Global variables for reuse across requests
global:
  variables:
    # API configuration
    BASE_URL: "https://api.example.com"
    API_VERSION: "v1"
    API_KEY: "${API_KEY}"

    # Computed variables
    API_ENDPOINT: "${BASE_URL}/${API_VERSION}"
    AUTH_HEADER: "Bearer ${API_KEY}"

    # Default values when environment variable not set
    TIMEOUT: "${REQUEST_TIMEOUT:5000}"

  defaults:
    headers:
      Authorization: "${AUTH_HEADER}"
    timeout: "${TIMEOUT}"

requests:
  - name: Get Users
    url: "${API_ENDPOINT}/users"
    method: GET

  - name: Create User
    url: "${API_ENDPOINT}/users"
    method: POST
    body:
      name: "John Doe"

# Global variables for reuse across requests
global:
  variables:
    # API configuration
    BASE_URL: "https://api.example.com"
    API_VERSION: "v1"
    API_KEY: "${API_KEY}"

    # Computed variables
    API_ENDPOINT: "${BASE_URL}/${API_VERSION}"
    AUTH_HEADER: "Bearer ${API_KEY}"

    # Default values when environment variable not set
    TIMEOUT: "${REQUEST_TIMEOUT:5000}"

  defaults:
    headers:
      Authorization: "${AUTH_HEADER}"
    timeout: "${TIMEOUT}"

requests:
  - name: Get Users
    url: "${API_ENDPOINT}/users"
    method: GET

  - name: Create User
    url: "${API_ENDPOINT}/users"
    method: POST
    body:
      name: "John Doe"

Advanced Configuration

Advanced global settings for complex scenarios including SSL and proxies.

Advanced Features

Some advanced features like proxies and rate limiting may require additional setup or may not be available in all environments. SSL/TLS certificate configuration is fully supported.

advanced-global-config.yaml

# Advanced global configuration
global:
  # Execution control
  execution: parallel
  continueOnError: true
  maxConcurrency: 5  # Limit concurrent requests in parallel mode

  # Advanced timeout settings
  timeout: 10000
  retries: 3
  retryDelay: 1000
  retryBackoff: 2.0
  retryOn: ["timeout", "5xx", "network"]

  # SSL/TLS settings
  ssl:
    verify: true
    ca: "./certs/ca.pem"
    cert: "./certs/client.pem"
    key: "./certs/client-key.pem"

  # Proxy settings
  proxy:
    http: "http://proxy.company.com:8080"
    https: "https://secure-proxy.company.com:8443"
    bypass: ["localhost", "*.internal.com"]

  # Output configuration
  output:
    verbose: true
    saveToFile: "results.json"
    format: "detailed"
    colors: true
    includeMetrics: true

  # Global variables
  variables:
    BASE_URL: "${API_BASE_URL:https://api.example.com}"
    API_KEY: "${API_KEY}"
    TRACE_ID: "${UUID}"

  # Global defaults
  defaults:
    headers:
      User-Agent: "curl-runner/1.0.0"
      X-Trace-ID: "${TRACE_ID}"
      Authorization: "Bearer ${API_KEY}"
    timeout: 8000
    retries: 2

# Advanced global configuration
global:
  # Execution control
  execution: parallel
  continueOnError: true
  maxConcurrency: 5  # Limit concurrent requests in parallel mode

  # Advanced timeout settings
  timeout: 10000
  retries: 3
  retryDelay: 1000
  retryBackoff: 2.0
  retryOn: ["timeout", "5xx", "network"]

  # SSL/TLS settings
  ssl:
    verify: true
    ca: "./certs/ca.pem"
    cert: "./certs/client.pem"
    key: "./certs/client-key.pem"

  # Proxy settings
  proxy:
    http: "http://proxy.company.com:8080"
    https: "https://secure-proxy.company.com:8443"
    bypass: ["localhost", "*.internal.com"]

  # Output configuration
  output:
    verbose: true
    saveToFile: "results.json"
    format: "detailed"
    colors: true
    includeMetrics: true

  # Global variables
  variables:
    BASE_URL: "${API_BASE_URL:https://api.example.com}"
    API_KEY: "${API_KEY}"
    TRACE_ID: "${UUID}"

  # Global defaults
  defaults:
    headers:
      User-Agent: "curl-runner/1.0.0"
      X-Trace-ID: "${TRACE_ID}"
      Authorization: "Bearer ${API_KEY}"
    timeout: 8000
    retries: 2

SSL/TLS Configuration

Configure SSL/TLS certificates globally for all requests. Individual requests can override these settings.

ssl-config.yaml

# Global SSL/TLS Configuration
global:
  # Apply SSL settings to all requests
  ssl:
    # Verify SSL certificates (default: true)
    verify: true

    # Custom CA certificate for enterprise environments
    ca: "./certs/company-ca.pem"

    # Client certificate for mutual TLS (mTLS)
    cert: "./certs/client.pem"
    key: "./certs/client-key.pem"

requests:
  # This request uses global SSL settings
  - name: "Uses Global SSL"
    url: "https://internal-api.company.com/data"
    method: GET

  # This request overrides global SSL settings
  - name: "Different SSL Config"
    url: "https://partner-api.example.com/data"
    method: GET
    ssl:
      ca: "./certs/partner-ca.pem"  # Override with different CA

# Global SSL/TLS Configuration
global:
  # Apply SSL settings to all requests
  ssl:
    # Verify SSL certificates (default: true)
    verify: true

    # Custom CA certificate for enterprise environments
    ca: "./certs/company-ca.pem"

    # Client certificate for mutual TLS (mTLS)
    cert: "./certs/client.pem"
    key: "./certs/client-key.pem"

requests:
  # This request uses global SSL settings
  - name: "Uses Global SSL"
    url: "https://internal-api.company.com/data"
    method: GET

  # This request overrides global SSL settings
  - name: "Different SSL Config"
    url: "https://partner-api.example.com/data"
    method: GET
    ssl:
      ca: "./certs/partner-ca.pem"  # Override with different CA

SSL Configuration Properties

Property	Type	Default	Description
`verify`	boolean	`true`	Whether to verify SSL certificates
`ca`	string	-	Path to CA certificate file
`cert`	string	-	Path to client certificate file for mTLS
`key`	string	-	Path to client private key file for mTLS

Note: Global SSL settings apply to all requests. Individual requests can override these settings by specifying their own ssl configuration.

Setting Precedence

Understanding how individual request settings override global settings.

Override Rules

1Individual Request SettingsAlways take precedence

2Collection-Level DefaultsOverride global defaults

3Global DefaultsApply when not overridden

setting-precedence.yaml

# How individual requests override global settings
global:
  execution: sequential
  timeout: 5000
  retries: 2
  defaults:
    headers:
      Accept: "application/json"
      User-Agent: "curl-runner/1.0.0"

requests:
  - name: Uses Global Settings
    url: https://api.example.com/users
    method: GET
    # Inherits: timeout=5000, retries=2, headers from defaults
    
  - name: Overrides Global Settings  
    url: https://slow-api.example.com/data
    method: GET
    timeout: 30000     # Overrides global timeout
    retries: 5         # Overrides global retries
    headers:
      Accept: "application/xml"  # Overrides global default
      User-Agent: "MyApp/2.0.0"  # Overrides global default
      Custom-Header: "value"     # Adds new header

# How individual requests override global settings
global:
  execution: sequential
  timeout: 5000
  retries: 2
  defaults:
    headers:
      Accept: "application/json"
      User-Agent: "curl-runner/1.0.0"

requests:
  - name: Uses Global Settings
    url: https://api.example.com/users
    method: GET
    # Inherits: timeout=5000, retries=2, headers from defaults
    
  - name: Overrides Global Settings  
    url: https://slow-api.example.com/data
    method: GET
    timeout: 30000     # Overrides global timeout
    retries: 5         # Overrides global retries
    headers:
      Accept: "application/xml"  # Overrides global default
      User-Agent: "MyApp/2.0.0"  # Overrides global default
      Custom-Header: "value"     # Adds new header