tgrs

Tigrister CLI - tgrs

A fast, modern HTTP client CLI built with Rust. Supports HTTP/1.1, HTTP/2, and HTTP/3 (QUIC) with built-in load testing, flow runner, assertions, and detailed request tracing.

Installation

npm

npm install -g @tigrister/tgrs

Homebrew

brew install tigrister/tap/tgrs

curl

curl -sSL https://cli.tigrister.com | sh

wget

wget -qO- https://cli.tigrister.com | sh

PowerShell (Windows)

irm https://cli.tigrister.com | iex

Verify your installation:

tgrs --version

Quick Start

# Simple GET request
tgrs GET https://api.example.com/users

# POST with JSON body
tgrs POST https://api.example.com/users name:John age:25

# POST with raw JSON
tgrs POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John", "age": 25}'

# Headers and auth
tgrs GET https://api.example.com/users -H "Accept: application/json" --bearer my-token

# Form data
tgrs POST https://api.example.com/upload -F "file=@photo.jpg" -F "caption=Hello"

Request Tracing (--trace)

Get a full timing breakdown of every phase in the request lifecycle:

tgrs GET https://api.example.com --trace

  Response Time                                          652.27 ms

  Prepare             █                                       6 µs
  DNS Lookup           █                                   3.47 ms
  TCP Handshake         ██████                           160.91 ms
  TLS Handshake               ██████████████             326.10 ms
  Request Send                              █               710 µs
  Server Response                            ███████     164.51 ms
  Download                                                   31 µs
  Processing                                                  1 µs

Use -t as shorthand:

tgrs GET https://api.example.com -t

Combine with verbose mode to see full request/response details alongside timing:

tgrs GET https://api.example.com -t -v

HTTP/3 (QUIC)

tgrs has native HTTP/3 support via QUIC - no extra configuration needed:

# Force HTTP/3
tgrs GET https://api.example.com --http3

# Force HTTP/2
tgrs GET https://api.example.com --http2

# Force HTTP/1.1
tgrs GET https://api.example.com --http1.1

When no protocol is forced, tgrs automatically negotiates the best available protocol and pools connections for reuse.

Assertions

Validate responses directly from the command line. Exit code 1 on failure - perfect for CI/CD:

# Status code
tgrs GET https://api.example.com --assert "status equals 200"

# Response time
tgrs GET https://api.example.com -a "response_time less_than 500"

# Body content
tgrs GET https://api.example.com -a "body contains success"

# JSON path
tgrs GET https://api.example.com -a "$.data.id exists"
tgrs GET https://api.example.com -a "$.users[0].name equals John"

# Headers
tgrs GET https://api.example.com -a "header Content-Type contains json"

# Multiple assertions
tgrs GET https://api.example.com \
  -a "status equals 200" \
  -a "response_time less_than 1000" \
  -a "body contains users"

Assertion Targets

Operators

Each operator has short and long forms. Use whichever feels more natural.

Short form examples:

tgrs GET https://api.example.com -a "status eq 200"
tgrs GET https://api.example.com -a "response_time lt 500"
tgrs GET https://api.example.com -a "$.data.count gt 0"

Random Data Generation

Generate dynamic test data with 25+ built-in generators:

# Random email and UUID
tgrs POST https://api.example.com/users \
  '{"email": "{{random.email}}", "id": "{{random.uuid}}"}'

# Random string with length
tgrs POST https://api.example.com/data name:"{{random.string(20)}}"

# Random number in range
tgrs POST https://api.example.com/data score:"{{random.number(1,100)}}"

# Pick from a list
tgrs POST https://api.example.com/data color:"{{random.enum(red,green,blue)}}"

# Custom pattern
tgrs POST https://api.example.com/data code:"{{random.custom([A-Z]{3}-\d{4})}}"

Available generators: uuid, email, name, string, number, boolean, date, ip, slug, url, phone, and more.

Flow Runner

Execute sequential API call chains defined in .flow.json files. Supports variable extraction, pre/post scripts, assertions, and retry logic.

# Run all flows in a directory
tgrs run api-tests

# Run a specific flow
tgrs run api-tests -f user-registration

# Run with environment
tgrs run api-tests -f user-registration -e dev

# Sequential iterations (5 times)
tgrs run api-tests -f user-registration -i 5

# Parallel execution (3 workers)
tgrs run api-tests -f user-registration -p 3

# Stop on first failure
tgrs run api-tests -f user-registration -c

If you are already inside the flow directory:

tgrs run
tgrs run -f flow-name

Flow Runner Flags

Variable Types

• {{flow.varName}} - Flow variables - carry data between steps
• {{varName}} - Environment variables
• {{random.type}} - Random value generated on each use

Exit Codes: 0 = all steps and assertions passed, 1 = failure

Features a live terminal dashboard with step-by-step progress, response times, assertion results, and anomaly detection.

Load Testing

Run load tests from .spec.json files with virtual users, stages, and thresholds.

# Run all specs in a directory
tgrs run spec-folder

# Run specific specs
tgrs run spec-folder -s user-api,auth-api

# Run with environment
tgrs run spec-folder -s user-api -e staging

# Stress test
tgrs run spec-folder -s user-api -t stress

# Spike test
tgrs run spec-folder -s user-api -t spike

# Soak test
tgrs run spec-folder -s user-api -t soak

Test Types

Load Test Flags

Includes a real-time terminal dashboard with live charts, response time percentiles, error tracking, and threshold monitoring.

Report Formats: HTML, PDF, OpenTelemetry JSON

CI/CD

tgrs works in any CI/CD pipeline. Assertions return exit code 1 on failure.

GitHub Actions

- name: API Health Check
  run: |
    curl -sSL https://cli.tigrister.com | sh
    tgrs GET https://api.example.com \
      -a "status eq 200" \
      -a "response_time lt 2000"

With npm/npx (no install needed)

- name: API Health Check
  run: npx --yes @tigrister/tgrs GET https://api.example.com -a "status eq 200"

GitHub Actions (Windows)

- name: API Health Check
  shell: pwsh
  run: |
    irm https://cli.tigrister.com | iex
    tgrs GET https://api.example.com -a "status eq 200"

GitLab CI

api-test:
  script:
    - curl -sSL https://cli.tigrister.com | sh
    - tgrs GET https://api.example.com -a "status eq 200"

Run flow tests in CI

- name: Run API Flow Tests
  run: |
    curl -sSL https://cli.tigrister.com | sh
    tgrs run ./tests -f smoke-test -e ci

Additional Features

Platform Support

Links

• Tigrister
• tgrs Documentation

License

Proprietary - Tigrister