Flow Runner

Chain multiple API calls into sequential flows with variable passing, assertions, retry logic, and parallel execution.

Getting Started

Running a Flow

Flows are defined as .flow.json files. Run them with the -f flag.

# Run a specific flow

tgrs run flow-folder-name -f user-registration

# Run with environment

tgrs run flow-folder-name -f user-registration -e dev

# Run 5 iterations sequentially

tgrs run flow-folder-name -f user-registration -i 5

# Run with 3 parallel workers

tgrs run flow-folder-name -f user-registration -p 3

# Stop on first failure

tgrs run flow-folder-name -f user-registration -c

Note: If you're already inside the flow folder, you can omit the path: tgrs run runs all flows in the current directory, or use tgrs run -f flow-name to select a specific one.

Variables

Variable Types

{{flow.varName}}Flow variables — carry data between steps (e.g., tokens, IDs)
{{varName}}Environment variables — see the Environments section for details
{{random.type}}Random variables — fresh random value each time

Parallel Execution

Iterations & Parallel

Run the same flow multiple times, sequentially or in parallel.

# Run 5 iterations sequentially

tgrs run flow-folder-name -f user-flow -i 5

# Run with 3 parallel workers

tgrs run flow-folder-name -f user-flow -p 3

Real-Time Dashboard

Terminal Dashboard

When you run a flow, tgrs displays a real-time terminal UI (TUI) dashboard showing:

  • Live charts — Response times over time
  • Step execution table — Status of each step with success/failure counts
  • Error tracking — Real-time error log with breakdown by type
  • Anomaly detection — Automatic detection of unusual patterns
  • Iteration summaries — Per-iteration statistics when using -i or -p

Exit Codes

Flow Result Codes

0All steps passed, all assertions passed
1One or more steps failed or assertions failed
Tip: Use exit codes in CI/CD pipelines to gate deployments based on API flow test results.

Export Reports

Report Formats

Export flow results in multiple formats for sharing and archiving.

  • HTML — Interactive report with embedded charts
  • PDF — Printable report
  • OpenTelemetry JSON — For integration with observability platforms
Tip: Reports can be exported and sent to external services using lifecycle scripts. See the Scripting section for detailed examples.

Environments

Environment Variables

Use environments to manage different configurations (dev, staging, prod) for your flows. Select an environment at runtime with -e / --env.

tgrs run flow-folder-name -f user-flow -e staging

Tip: Environments are created and managed in Tigrister Pro. See the Environments section for more details.

Vault Integration

HashiCorp Vault

Environment variables can be sourced from HashiCorp Vault for secure secret management. Provide vault credentials at runtime with VAULT_AUTH environment variables.

VAULT_AUTH="hvs.token@http://vault:8200" \

tgrs run flow-folder-name -f user-flow -e dev

Tip: See the Vault section for detailed configuration, multiple connections, and authentication methods.

Quick Reference

Flow Runner Flags

FlagAliasDescription
-f--flowFlow names (comma separated)
-e--envEnvironment name
-i--iterationsNumber of iterations (default: 1)
-p--parallelParallel execution count (default: 1)
-c--stop-on-failureStop on first failure
VAULT_AUTHVault credentials (credentials@url)
VAULT_AUTH_<NAME>Named vault connection (e.g., VAULT_AUTH_PROD)
Sessions & StorageLoad Testing