atra

Atrahasis CLI - atra

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 @atrahasis/cli

Homebrew

brew install atrahasisdev/tap/atra

curl

curl -sSL https://cli.atrahasis.dev | sh

wget

wget -qO- https://cli.atrahasis.dev | sh

PowerShell (Windows)

irm https://cli.atrahasis.dev | iex

Verify your installation:

atra --version

Quick Start

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

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

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

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

# Form data
atra POST https://api.example.com/upload -F "[email protected]" -F "caption=Hello"

Request Tracing (--trace)

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

atra 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:

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

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

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

HTTP/3 (QUIC)

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

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

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

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

When no protocol is forced, atra 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
atra GET https://api.example.com --assert "status equals 200"

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

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

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

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

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

Assertion Targets

| Target | Syntax | Description | |--------|--------|-------------| | status | status operator value | HTTP status code (e.g., 200, 404, 500) | | response_time | response_time operator ms | Response time in milliseconds | | header | header name operator value | Response header value (case-insensitive name) | | body | body operator value | Full response body as string | | $. | $.path operator value | JSON path - dot notation with array indexing (e.g., $.users[0].name) |

Operators

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

| Short | Long | Description | |-------|------|-------------| | eq | equals | Exact match | | neq | not_equals | Not equal | | gt | greater_than | Numeric greater than | | lt | less_than | Numeric less than | | | contains | String contains | | | not_contains | String does not contain | | | exists | Value exists (not null) | | | not_exists | Value is null or missing | | | is_empty | Empty string, array, or object | | | is_not_empty | Non-empty value | | | matches_regex | Regex pattern match | | | is_type | Check JSON type (string, number, boolean, array, object, null) |

Short form examples:

atra GET https://api.example.com -a "status eq 200"
atra GET https://api.example.com -a "response_time lt 500"
atra 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
atra POST https://api.example.com/users \
  '{"email": "{{random.email}}", "id": "{{random.uuid}}"}'

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

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

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

# Custom pattern
atra 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
atra run api-tests

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

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

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

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

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

If you are already inside the flow directory:

atra run
atra run -f flow-name

Flow Runner 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 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
atra run spec-folder

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

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

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

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

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

Test Types

| Type | VUs | Ramp | Duration | Purpose | |------|-----|------|----------|---------| | load (default) | 50 | 30s | 60s | Gradual ramp up, sustained load, gradual ramp down | | stress | 200 | 10s | 60s | Aggressive increase to find breaking points | | spike | 300 | 2s | 30s | Sudden spike to high load | | soak | 30 | 30s | 300s | Long duration with low, steady load | | custom | Custom | Custom | Custom | User-defined stages |

Load Test Flags

| Flag | Alias | Description | |------|-------|-------------| | -s | --spec | Spec names (comma-separated) | | -t | --type | Test type | | -e | --env | Environment name |

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

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

GitHub Actions

- name: API Health Check
  run: |
    curl -sSL https://cli.atrahasis.dev | sh
    atra 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 @atrahasis/cli GET https://api.example.com -a "status eq 200"

GitHub Actions (Windows)

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

GitLab CI

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

Run flow tests in CI

- name: Run API Flow Tests
  run: |
    curl -sSL https://cli.atrahasis.dev | sh
    atra run ./tests -f smoke-test -e ci

Additional Features

| Feature | Flag | |---------|------| | Follow redirects | -L | | Timeout | -m 30 | | Retry on failure | --retry 3 | | Skip TLS verification | -k | | Basic auth | -u user:pass | | Bearer token | --bearer token | | OAuth 2.0 | --oauth2 flow:url:id:secret | | Download file | -D output.zip | | Cookie support | -b "key=value" | | Named sessions | -N my-session | | Verbose output | -v | | JSON output | --json | | Dry run | -r | | Certificate info | -C | | Silent mode | -s |

Platform Support

| Platform | Architecture | Status | |----------|-------------|--------| | macOS | Apple Silicon (arm64) | Available | | macOS | Intel (x86_64) | Available | | Linux | arm64 | Available | | Linux | x86_64 | Available | | Windows | x86_64 | Available |

Links

• Atrahasis
• atra Documentation

License

Proprietary - Atrahasis