Scout CLI

Command-line interface for Scout QA automation platform.

Installation

npm install -g @scoutqa/cli

Authentication

The CLI supports multiple authentication methods (in priority order):

1. Environment variable (highest priority)
2. OAuth login (via browser)
3. API key (stored in config file)

Environment Variables

• SCOUT_API_KEY: API key for authentication
• SCOUT_SERVER_URL: Scout server URL (default: https://scoutqa.ai)

Example:

export SCOUT_API_KEY=sk-scout-xxx
export SCOUT_SERVER_URL=https://custom-scout-instance.com

OAuth Login

scoutqa auth login

Opens your browser for authentication. Stores access and refresh tokens locally.

API Key

Set an API key manually:

scoutqa auth set-api-key <your-api-key>

Or create a new API key:

scoutqa auth create-api-key --name "My CLI Key" --expires-in 90d

Commands

Authentication

• scoutqa auth status - Show authentication status
• scoutqa auth login - Login via browser (OAuth)
• scoutqa auth set-api-key - Set API key manually
• scoutqa auth create-api-key - Create a new API key
• scoutqa auth logout - Clear stored credentials

Executions

• scoutqa create-execution --url <url> --prompt <prompt> - Create a new test execution
• scoutqa list-executions - List your executions
• scoutqa send-message --execution-id <id> --prompt <prompt> - Send a message to an execution

Configuration

Configuration is stored in ~/.config/scoutqa/config.json (or platform-specific config directory).

Priority order for settings:

1. Environment variables (SCOUT_API_KEY, SCOUT_SERVER_URL)
2. Config file
3. Defaults

Testing Local/Intranet URLs

The CLI supports testing local and intranet URLs using Cloudflare Tunnel. This allows cloud-based agents to access applications running on your local machine or private network.

No additional setup is required - the CLI automatically manages the tunnel binary.

How It Works

When you run a test against a local URL (e.g., http://localhost:3000):

1. The CLI detects the local URL
2. The server creates a secure Cloudflare Tunnel and returns a tunnel token
3. The CLI automatically downloads (if needed) and starts cloudflared to establish the tunnel
4. The cloud agent accesses your local app through the tunnel
5. When the execution completes, the tunnel is automatically cleaned up

Supported URL Types

• Loopback addresses: localhost, 127.0.0.1
• Private networks: 192.168.x.x, 10.x.x.x, 172.16-31.x.x
• Link-local: 169.254.x.x
• mDNS hostnames: *.local
• Single-label hosts: intranet, myserver

Note: IPv6 addresses are not supported.

Example

# Start your local app
npm run dev  # Runs on localhost:3000

# In another terminal, run Scout
scoutqa create-execution \
  --url http://localhost:3000 \
  --prompt "Test the homepage"

The CLI will automatically set up the tunnel and connect your local app to the cloud agent.

Examples

Create and run a test

scoutqa create-execution \
  --url https://example.com \
  --prompt "Test the login functionality"

Continue an existing execution

scoutqa send-message \
  --execution-id exec_123 \
  --prompt "Now test the logout button"

Use with custom server

export SCOUT_SERVER_URL=https://staging.scoutqa.ai
scoutqa auth login