BotGauge CLI

Command-line interface for running and managing BotGauge test suites from CI/CD pipelines and local environments.

Install

npm install -g @botgauge/cli

Requirement: Node.js 20+

Verify installation:

botgauge --version

Quick Start

Set credentials:

export BOTGAUGE_BASE_URL=https://your-base-url
export BOTGAUGE_API_KEY=<your-api-key>
export BOTGAUGE_API_PREFIX=/platform/v1/api

Run a suite:

botgauge suite run <suite_id>

Run and wait for completion:

botgauge suite run <suite_id> --wait

JSON output for CI:

botgauge suite run <suite_id> --wait --json > result.json

JUnit report:

botgauge suite run <suite_id> --wait --junit results/junit.xml

Commands

botgauge suite run <suite_id>       # Trigger a test suite
botgauge suite list                 # List available suites
botgauge run summary <run_id>       # Get run summary
botgauge run details <run_id>       # Get detailed run info
botgauge config set                 # Save configuration
botgauge config view                # View active config
botgauge whoami                     # Show authenticated user

Common Examples

List suites:

botgauge suite list --json

Check run summary:

botgauge run summary <run_id> --json

Check run details:

botgauge run details <run_id> --json

Save config:

botgauge config set \
  --base-url https://your-base-url \
  --api-key <your-api-key> \
  --api-prefix /platform/v1/api

View config:

botgauge config view

Configuration

Configuration priority (highest first):

1. CLI flags
2. Environment variables
3. Config file
4. Defaults

Supported environment variables:

BOTGAUGE_BASE_URL        # API base URL
BOTGAUGE_API_KEY         # API authentication key
BOTGAUGE_API_PREFIX      # API path prefix (default: /platform/v1/api)
BOTGAUGE_POLL_INTERVAL   # Polling interval in seconds
BOTGAUGE_TIMEOUT         # Max wait time in seconds

Default config file:

~/.config/botgauge/config.json

Example config:

{
  "base_url": "https://your-base-url",
  "api_key": "<your-api-key>",
  "api_prefix": "/platform/v1/api",
  "timeout": 1800
}

Key Options

Shared

| Option | Description | |--------|-------------| | --json | Output results in JSON format | | --base-url <url> | BotGauge API base URL | | --api-key <key> | API authentication key | | --api-prefix <prefix> | API path prefix | | --config <path> | Custom config file path | | --no-config | Ignore config file |

suite run

| Option | Description | |--------|-------------| | --wait | Wait for suite completion | | --poll-interval <s> | Polling interval in seconds (min: 10s, default: adaptive) | | --timeout <s> | Max wait time in seconds (default: 1800) | | --junit <path> | Generate JUnit XML report | | --log-file <path> | Tee logs to file (atomic writes) | | --metadata <json> | trigger metadata as a JSON string | | --idempotency-key <key> | Override auto-generated idempotency key | | --cancel-on-signal | Cancel remote run on Ctrl+C / SIGTERM | | --verbose | Show diagnostic logs |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Tests passed | | 1 | Tests failed or CLI error | | 2 | Timed out while waiting |

Trigger Metadata Example

Use AUT_URL to override the application under test URL and data to override global test data (optional):

botgauge suite run <suite_id> --wait \
  --metadata '{"AUT_URL": "https://botgauge.com", "data": {"username": "user1"}}'

CI Example

botgauge suite run <suite_id> \
  --wait \
  --json \
  --junit results/junit.xml \
  --timeout 3600 \
  --metadata '{"AUT_URL": "https://botgauge.com", "data": {"username": "user1"}}' \
  > result.json

License

MIT