ReAPI CLI

A command-line tool for running API tests and managing test deployments.

Installation

Option 1: npx (Recommended)

No installation needed! Use npx to run the latest version:

# Run with npx (auto-install if needed)
npx @reapi/cli -y test run ./deployment.json

# For CI/CD environments (skip prompts)
npx @reapi/cli -y test run remote://id --api-key "$API_KEY"

Option 2: Global Installation

npm install -g @reapi/cli
# or
pnpm add -g @reapi/cli

# Then run without npx
reapi test run ./deployment.json

Quick Start

# Local test (results stay on your machine)
npx @reapi/cli -y test run ./deployment.json

# Remote test (results uploaded to cloud with visualizations & notifications)
npx @reapi/cli -y test run remote://your-deployment-id --api-key "your-api-key"

💡 Tip: Use remote:// for CI/CD and team collaboration (auto-uploads results + notifications). Use local files for development and debugging (fully private).

Complete Parameter Reference

🎯 Test Target

🔐 Authentication & Access

Environment Variables:

• REAPI_API_KEY - Default API key environment variable

Priority (highest to lowest):

1. --api-key command-line parameter
2. apiKey in config file
3. Environment variable specified by --api-key-env
4. REAPI_API_KEY default environment variable

🌍 Environment Variables Override

Environment variables file will override vars in deployment, used for passing production credentials.

📁 File Upload

Required when tests include file uploads (images, PDFs, etc.). File names will be matched with the file mapping in deployment.

📊 Output & Reports

Report Types:

• junit - JUnit XML format (for CI integration)
• html - HTML format (for visualization)

Date Format Examples:

• yyyy-MM-dd'['HH:mm']' → 2024-01-15[14:30].json
• yyyyMMdd_HHmmss → 20240115_143000.json
• '[prod]'yyyy-MM-dd → [prod]2024-01-15.json

⚡ Performance Optimization

Controls how many test nodes can execute concurrently within Parallel nodes. Adjust based on server performance and load tolerance.

🛠️ Execution Control

Set to true in CI/CD to interrupt build pipeline on test failures.

⚙️ Configuration File

If not specified, CLI will automatically search for:

1. reapi.yaml
2. reapi.json

Remote vs Local Test Execution

🌐 Remote Execution (remote://)

When you run tests using a remote:// URI:

npx @reapi/cli -y test run remote://deployment-id --api-key "your-key"

How it works:

1. 📥 CLI downloads test configuration (deployment bundle) from cloud
2. 🖥️ Tests run locally on your machine (can access localhost, private networks, VPNs)
3. 📤 Results automatically upload to cloud for visualization

Benefits:

• ✅ Local Network Access - Test localhost, internal APIs, databases, private services
• ✅ Automatic Upload - Test results automatically uploaded to cloud
• ✅ Visual Dashboard - View results in ReAPI's web interface with charts and detailed logs
• ✅ Team Collaboration - Share results with your team via URL
• ✅ Notifications - Trigger email, Slack, or webhook notifications on test completion
• ✅ History & Trends - Track test results over time
• ✅ CI/CD Integration - Results are linked to your deployment for easy tracking

Perfect for:

• Testing internal/private APIs that aren't publicly accessible
• CI/CD pipelines in your infrastructure
• Testing against localhost during development
• APIs behind VPN or firewall

💻 Local Execution (File Path)

When you run tests using a local file path, results are saved only to your local machine:

npx @reapi/cli -y test run ./deployment.json --output ./results

Characteristics:

• ⚠️ No Cloud Upload - Results stay on your local machine
• ⚠️ No Notifications - No email/Slack alerts
• ✅ Privacy - Test data never leaves your machine
• ✅ No API Key Required - Run without authentication
• ✅ Offline Testing - Works without internet connection

Perfect for: Local development, debugging, offline testing, privacy-sensitive tests

Quick Comparison

📊 vs ReAPI Serverless Runner

ReAPI also offers a Serverless Runner that runs tests entirely in the cloud:

Use CLI with remote:// when:

• Testing private/internal APIs
• Need access to localhost or VPN
• Running in your CI/CD pipeline
• Want full control over execution environment

Use Serverless Runner when:

• Testing public APIs only
• Want zero infrastructure setup
• Need built-in scheduling
• Don't want to manage execution environment

Recommended: Using Configuration File

Why Use Configuration File?

• ✅ Avoid repetition - No need to type long parameters every time
• ✅ Team collaboration - Configuration files can be committed to Git
• ✅ Environment management - Different configs for different environments
• ✅ More secure - Sensitive info won't appear in command history

Create Configuration File

Create reapi.yaml in your project root:

# Basic configuration
target: ./deployment.json
output: ./test-results

# Authentication
apiKey: sk_dev_xxxxx # Development environment only

# Environment variables (recommended for production)
env: ./prod-env.json

# File upload
filesDir: ./test-files

# Reports
report: junit,html
reportPath: ./reports
dateFormat: yyyy-MM-dd'['HH:mm']'

# Performance
concurrency: 8

# CI/CD
throwOnFailure: true

Use Configuration File

# Auto-detect configuration file (using npx)
npx @reapi/cli -y test run

# Or specify explicitly
npx @reapi/cli -y test run --config ./reapi.yaml

# Command-line parameters can override config file
npx @reapi/cli -y test run --config reapi.yaml --output ./custom-results

Typical Use Cases

Scenario 1: Local Development

reapi.yaml:

target: ./deployment.json
env: ./dev-env.json
filesDir: ./test-files
output: ./test-results
concurrency: 4

Run:

npx @reapi/cli -y test run
# or with global installation
reapi test run

Scenario 2: CI/CD Integration

reapi-ci.yaml:

target: remote://your-deployment-id # Use remote:// for automatic cloud upload
env: ./ci-env.json # Generated from CI secrets
output: ./test-results
report: junit
reportPath: ./reports
throwOnFailure: true
concurrency: 10

Why use remote:// in CI/CD?

• ✅ Test results automatically uploaded to cloud
• ✅ Visual dashboard for easy result review
• ✅ Email/Slack notifications on failure
• ✅ Historical tracking and trends
• ✅ Team can view results without accessing CI logs

CI Script:

# .github/workflows/api-test.yml
steps:
  - name: Generate secrets file
    run: echo '{"apiKey":"${{ secrets.REAPI_API_KEY }}"}' > ci-env.json

  - name: Run tests
    run: npx @reapi/cli -y test run --config reapi-ci.yaml

Scenario 3: Multi-Environment Configuration

project/
  ├── reapi.dev.yaml      # Development
  ├── reapi.staging.yaml  # Staging
  ├── reapi.prod.yaml     # Production
  └── envs/
      ├── dev-env.json
      ├── staging-env.json
      └── prod-env.json    # Add to .gitignore

# Development environment
npx @reapi/cli -y test run --config reapi.dev.yaml

# Production environment
npx @reapi/cli -y test run --config reapi.prod.yaml

Security Best Practices

API Key Management

Recommended approaches (by priority):

1️⃣ Environment Variables File (Most Recommended)

# reapi.yaml
env: ./secrets.json # ← Add to .gitignore

// secrets.json
{
  "apiKey": "sk_prod_xxxxx",
  "dbPassword": "secret"
}

2️⃣ System Environment Variables

export REAPI_API_KEY="sk_prod_xxxxx"
reapi test run

3️⃣ CI/CD Secrets

# GitHub Actions
- name: Run tests
  env:
    REAPI_API_KEY: ${{ secrets.REAPI_API_KEY }}
  run: npx @reapi/cli -y test run remote://deployment-id

❌ Not Recommended: Command-line Parameter

# Will remain in command history
npx @reapi/cli -y test run --api-key "sk_prod_xxxxx"

.gitignore Configuration

# Sensitive information
*-env.json
secrets.json
prod-*.json

# Test results
test-results/
reports/

Environment Variables Override Mechanism

Environment variables file is used to override vars in deployment, perfect for passing production credentials.

Deployment vars:

{
  "vars": {
    "baseUrl": "https://api.example.com",
    "apiKey": "placeholder"
  }
}

Environment file (prod-env.json):

{
  "apiKey": "actual-production-key-12345",
  "dbPassword": "super-secret"
}

Final runtime variables:

{
  "baseUrl": "https://api.example.com",
  "apiKey": "actual-production-key-12345", // ✅ Overridden
  "dbPassword": "super-secret" // ✅ Added
}

File Upload Guide

If tests include file uploads, use the --files-dir parameter:

Directory Structure

project/
  ├── reapi.yaml
  ├── deployment.json
  └── test-files/
      ├── avatar.png
      ├── document.pdf
      └── data.csv

Configuration

filesDir: ./test-files

How It Works

1. Deployment config contains file mapping: { fileId: "fileName" }
2. CLI searches for files by name in filesDir
3. Automatically detects Content-Type
4. Streams files to server (supports large files)

Notes

• Files must exist in filesDir root directory (no recursive search)
• File names must match the mapping in deployment config
• Missing files will cause test failure with detailed error messages

Complete Configuration Example

# reapi.yaml - Production environment full configuration

# ========== Basic Configuration ==========
target: remote://a9d3d829-a138-4da8-8c5b-cb8418f96539

# ========== Authentication ==========
# Not recommended to hardcode production key in config file
# apiKey: sk_prod_xxxxx

# ========== Environment Variables (Recommended) ==========
env: ./prod-secrets.json # Add to .gitignore

# ========== File Upload ==========
filesDir: ./test-files

# ========== Output & Reports ==========
output: ./test-results
report: junit,html
reportPath: ./reports
dateFormat: yyyy-MM-dd'['HH:mm']'

# ========== Performance Optimization ==========
concurrency: 8

# ========== CI/CD ==========
throwOnFailure: true

Command-line Examples

Basic Usage

# Using npx (recommended for CI/CD and automation)
npx @reapi/cli -y test run ./deployment.json

# With global installation
reapi test run ./deployment.json

# Remote deployment
npx @reapi/cli -y test run remote://deployment-id --api-key "your-key"

# Using config file
npx @reapi/cli -y test run --config reapi.yaml

Environment Variables

# Using environment file
npx @reapi/cli -y test run deployment.json --env ./prod-env.json

# Using system environment variable
export REAPI_API_KEY="your-key"
npx @reapi/cli -y test run remote://deployment-id

# Using custom environment variable
export MY_TOKEN="your-key"
npx @reapi/cli -y test run remote://id --api-key-env MY_TOKEN

File Upload

# Specify files directory
npx @reapi/cli -y test run deployment.json --files-dir ./test-files

# Absolute path
npx @reapi/cli -y test run deployment.json --files-dir /absolute/path/to/files

Output & Reports

# Custom output directory
npx @reapi/cli -y test run deployment.json --output ./custom-results

# Only generate JUnit report
npx @reapi/cli -y test run deployment.json --report junit

# Custom report path
npx @reapi/cli -y test run deployment.json --report-path ./my-reports

# Custom date format
npx @reapi/cli -y test run deployment.json --date-format "yyyyMMdd_HHmmss"

Performance Tuning

# Increase concurrency for Parallel nodes
npx @reapi/cli -y test run deployment.json --concurrency 10

# Reduce concurrency (resource-constrained environment or sensitive servers)
npx @reapi/cli -y test run deployment.json --concurrency 2

CI/CD

# Exit on failure (for CI)
npx @reapi/cli -y test run deployment.json --throw-on-failure

Parameter Combination

# Complete example
npx @reapi/cli -y test run remote://abc123 \
  --api-key "sk_prod_xxxxx" \
  --env ./prod-env.json \
  --files-dir ./test-files \
  --output ./results \
  --report junit,html \
  --report-path ./reports \
  --concurrency 8 \
  --throw-on-failure

Getting Help

# View all commands
npx @reapi/cli -y --help

# View test run command help
npx @reapi/cli -y test run --help

# With global installation
reapi --help
reapi test run --help

FAQ

Q: How do I view detailed logs?

A: CLI automatically outputs colored logs showing execution progress, warnings, and error messages.

Q: Must the config file be YAML?

A: No. Both reapi.yaml and reapi.json formats are supported.

Q: How do I avoid leaking credentials in CI?

A: Use environment variables file and dynamically generate it from CI secrets. Don't commit it to Git.

# GitHub Actions example
- name: Create secrets file
  run: echo '{"apiKey":"${{ secrets.API_KEY }}"}' > secrets.json
- name: Run tests
  run: npx @reapi/cli -y test run --env secrets.json

Q: Tests failed but process didn't exit?

A: Set throwOnFailure: true in config file, or use --throw-on-failure parameter.

Q: What if file upload fails?

A: Check:

1. Is --files-dir parameter specified?
2. Do files exist in the specified directory?
3. Do file names match the deployment config?
4. Check detailed hints in error messages

Q: What's a good concurrency setting?

A:

• Default 6 works for most scenarios
• This setting only affects Parallel nodes (controls how many branches execute simultaneously)
• High-performance servers can increase to 10-20
• Resource-constrained or load-sensitive target servers should reduce to 2-4
• Sequential test nodes are unaffected by this setting

Q: What if command-line parameters conflict with config file?

A: Command-line parameters have higher priority and will override config file settings.

Q: When should I use remote:// vs local files?

A:

Use remote:// when:

• Testing internal/private APIs (localhost, intranet, VPN)
• Running in CI/CD pipelines
• Need team visibility of test results
• Want automatic notifications (email/Slack)
• Need historical tracking and trends
• Want visual dashboards with charts
• Testing behind firewall but want cloud visibility

Use local files when:

• Developing and debugging locally
• Need complete privacy (config + data never sent to cloud)
• Testing without internet connection
• Don't need team collaboration features
• Prototyping or one-off tests

Q: How do I get notifications when tests fail?

A: Notifications are automatic when using remote:// deployment URIs:

1. Configure in ReAPI Web UI:

   • Go to your deployment settings
   • Set up email, Slack webhook, or custom webhook URLs
   • Choose trigger conditions (e.g., only on failure)

2. Run with remote://:

   npx @reapi/cli -y test run remote://deployment-id --api-key "key"

3. Automatic notifications sent when:

   • Tests complete
   • Tests fail
   • Specific conditions you configured are met

Note: Local file execution (./deployment.json) does NOT trigger notifications.

Q: Can I see test results visually?

A: Yes! When using remote://, test results are automatically uploaded and you can:

• View detailed results in ReAPI's web dashboard
• See success/failure charts and trends
• Drill down into individual request/response details
• Share result URLs with your team
• Compare results across test runs

Access your results at: https://app.reapi.com/projects/{project}/deployments/{deployment}/results

Q: Can I test localhost or internal APIs with CLI?

A: Yes! This is a key advantage of CLI over serverless runners:

# CLI runs on YOUR machine, so it can access:
npx @reapi/cli -y test run remote://id --api-key "key"

CLI can test:

• ✅ localhost:3000 - Your local dev server
• ✅ 192.168.x.x - Private network IPs
• ✅ Internal APIs behind VPN
• ✅ Database connections on your network
• ✅ Services behind corporate firewall

Serverless Runner cannot test:

• ❌ Localhost or private IPs (runs in cloud, not on your machine)
• ✅ Only public APIs accessible from internet

Architecture:

• remote:// = Download config from cloud → Run locally → Upload results
• Serverless = Everything runs in ReAPI's cloud infrastructure

Q: Do I need to install anything on my server for CLI tests?

A: No! The CLI runs on:

• Your local machine
• Your CI/CD runners (GitHub Actions, GitLab CI, Jenkins, etc.)

Your API servers don't need any ReAPI software. The CLI just makes HTTP requests like any other API client.

Migration Guide (from Old CLI)

If you're migrating from the old @reapi/cli2, only one thing to note:

Parameter Changes

New Features

• ✅ --files-dir - File upload support
• ✅ --config - Configuration file support
• ✅ --concurrency - Concurrency control
• ✅ --api-key-env - Custom environment variable
• ✅ --date-format - Date formatting
• ✅ Auto config file detection

All other parameters remain compatible!

Start using ReAPI CLI to make API testing simpler! 🚀