CLI Flow Runner

Chain multiple API requests into automated workflows. Run .flow.json files from the terminal with variable extraction, assertions, retry logic, pre/post scripts, and a live terminal dashboard.

Quick Start

# Run all flows in a directory
tgrs run order-flows

# Run a specific flow
tgrs run order-flows -f place-order

# Run with environment variables
tgrs run order-flows -f place-order -e dev

# Sequential iterations
tgrs run order-flows -f place-order -i 5

# Parallel workers
tgrs run order-flows -f place-order -p 4

# Stop on first failure
tgrs run order-flows -f place-order -c

Flags

Flag	Alias	Description
-f	--flow	Flow names (comma-separated)
-e	--env	Environment name
-i	--iterations	Iteration count (default: 1)
-p	--parallel	Parallel worker count (default: 1)
-c	--stop-on-failure	Stop on first failure

Variable Extraction & Chaining

Extract values from responses and use them in subsequent steps:

Source	Expression	Example
JSON Path	Dot notation on response body	data.token
Header	Response header name	X-Request-Id
Regex	First capture group	id":(\d+)
Status Code	HTTP status code	200

Use extracted variables with {{flow.varName}} syntax in any subsequent step's URL, headers, body, or assertions.

Two Variable Systems

Syntax	Source	Lifetime	Use Case
{{flow.varName}}	Extractions and scripts	Current run	Tokens, IDs, dynamic data
{{varName}}	Environment variables	Persistent	Base URLs, API keys

Pre/Post Scripts

Write JavaScript to control the request lifecycle. The tg scripting API is available in every script:

Pre-request script - Modify the request before it's sent:

// Set dynamic URL
tg.request.url = "https://api.example.com/users/" + tg.flow.get("userId");

// Add computed header
tg.request.setHeader("X-Timestamp", Date.now().toString());

// Set request body
tg.request.body = JSON.stringify({ key: "value" });

Post-response script - Inspect response and extract data:

// Store response data in flow variables
tg.flow.set("token", tg.response.json().access_token);
tg.flow.set("status", tg.response.status);

// Log response timing
console.log("TTFB:", tg.response.timing.ttfb);

Lifecycle scripts - beforeAll and afterAll run once per flow execution:

// beforeAll - setup
tg.flow.set("token", "initial-value");

// afterAll - export reports
var html = tg.export.html();
fetch("https://webhook.example.com/report", {
  method: "POST",
  headers: { "Content-Type": "text/html" },
  body: html,
});

Live Dashboard

The terminal dashboard displays in real-time:

• Summary cards - Duration, success rate, average response time, data transfer
• Response time chart - Per-step line chart with color-coded flows
• Steps table - Method, URL, status code, response time, assertions
• Anomaly detection - Flags unstable response times and performance regressions

Iterations & Parallel Execution

Run the same flow multiple times to detect regressions:

• -i 5 runs 5 sequential iterations
• -p 4 runs 4 parallel workers

Each iteration appears as a separate line on the response time chart. The anomaly detection engine highlights unstable response times automatically.

Export Reports

Generate reports from afterAll scripts:

• HTML - Interactive report with charts
• PDF - Printable documentation
• JSON - OpenTelemetry-compatible format for CI/CD pipelines

Exit Codes

• 0 - All steps and assertions passed
• 1 - Any step or assertion failed

Tags: flow-runner, automation, testing, workflow, scripting