CLI Reference

Complete reference for the Quadrastack CLI (quadrastack), including usage, flags, environment variables, and configuration.

Overview

Quadrastack is a single-binary CLI tool that finds and executes HTTP workflows defined in YAML playbooks.

Syntax

quadrastack [flags]

Basic Examples

# Run all requests in the current directory
quadrastack

# Validate playbooks without executing
quadrastack --dry-run

# Run with verbose logging
quadrastack --verbose

---

Flags

All flags are optional. You can also configure most of these via a config file or environment variables.

Flag	Short	Default	Description
--playbook-dir	-d	.	Directory containing playbook YAML files (recursive)
--request	None	None	Run specific named request(s) (repeatable)
--scenario	None	None	Run requests matching a scenario's label selector (repeatable)
--profile	None	default	Name of the variables profile to use from vars.yaml
--output-dir	-o	.	Directory to write results to
--output-dir-mode	None	timestamped	timestamped (creates unique subdir) or flat (overwrites)
--output-detail	None	compact	compact (truncated bodies) or full (complete bodies)
--mock-server	None	None	Start named mock server(s) instead of running tests
--config	None	None	Path to a YAML config file
--dry-run	None	false	Validate inputs/YAML without executing requests
--verbose	None	false	Enable detailed debug logging
--license-info	None	false	Display license information and exit
--version	-v	false	Display version information
--help	-h	false	Display help

Detailed Usage Examples

Run All Tests in a Directory (-d)

Recursively searches for .yaml files in the given directory.

quadrastack -d ./tests/integration

Run Specific Tests (--request)

Run specific requests by their ID. You can repeat the flag to run multiple.

# Single request
quadrastack --request create-user

# Multiple requests (execution order is preserved)
quadrastack --request create-user --request delete-user

Run Scenarios (--scenario)

Run requests matching a scenario's label selector.

# Run 'smoke' scenario
quadrastack --scenario smoke

# Run multiple scenarios in parallel (Pro tier)
quadrastack --scenario smoke --scenario regression

Output Configuration

Control where and how results are saved.

# Flat output mode (overwrites files, great for CI)
quadrastack --output-dir ./results --output-dir-mode flat

# Full detail mode (includes complete response bodies in JSON)
quadrastack --output-detail full

Mock Server Mode

Start one or more mock servers defined in your playbooks. This mode blocks until stopped (Ctrl+C).

# Start a specific mock server
quadrastack --mock-server payment-api

# Start multiple servers
quadrastack --mock-server payment-api --mock-server user-api

---

Environment Variable Overrides

You can override any value in your vars.yaml profile using system environment variables. This is critical for CI/CD security (injecting API keys).

Syntax

Quadrastack maps environment variables to variable keys by:

1. Lowercasing the env var.
2. Replacing underscores _ with dots ..

Examples

Environment Variable	Maps to Variable Key	Value
BASE_URL	base.url	https://api.com
STRIPE_KEY	stripe.key	sk_test_...
AUTH_USER_PASSWORD	auth.user.password	12345

Usage

# Provide a dynamic API URL and secret token
BASE_URL=https://staging.api.com 
AUTH_TOKEN=secret-123 quadrastack --profile staging

---

Configuration File

You can allow defaults using a YAML configuration file.

Flag Precedence:

1. CLI Flags (Highest)
2. Environment Variables (for vars)
3. Config File
4. Defaults (Lowest)

Usage

quadrastack --config ./quadrastack.config.yaml

File Format

# quadrastack.config.yaml

# Directory containing playbook YAML files
playbookDir: ./tests/e2e

# Profile to use from vars.yaml
profile: staging

# Output configuration
outputDir: ./artifacts
outputDirMode: flat
outputDetail: compact

# Default scenarios to run if no flags provided
scenarios:
  - smoke-tests

# Default mock servers to start
mockServers:
  - api-mock

---

Exit Codes

Quadrastack returns standard exit codes to indicate success or failure, making it effectively for CI/CD pipelines.

Code	Meaning
0	Success: All requests executed and all assertions passed.
1	Failure: At least one test failed, or there was a configuration/validation error.