Home / Documentation / CLI Reference
Documentation

Getting Started

CLI

Infrastructure

Community

CLI Reference

Distributed Playwright testing from your terminal. Run your test suite across EC2 Spot instances on your own AWS account — traces collected for every test.

Installation

Install the CLI globally:

npm install -g traceloom

Or run without installing:

npx traceloom <command>

Requires Node.js 20 or later.

Quick Start

# 1. Authenticate with your API key
traceloom auth

# 2. Initialize your project
traceloom init

# 3. Run your tests
traceloom run

Commands

traceloom auth

Store your API key locally or pass it directly for CI use.

traceloom init

Create a .traceloom.yml config file in your project directory.

traceloom run

Submit your Playwright tests for distributed execution across EC2 Spot workers.

traceloom runs

List recent test runs or view details for a specific run including trace URLs.

CI/CD Integration

Use the CLI in GitHub Actions and other CI pipelines with env var auth and plain text output.

Config File

traceloom init creates a .traceloom.yml in your project root: 

customer: your-customer-id
project: your-project-id
apiUrl: https://api.traceloom.io   # optional
Field Required Description
customer Yes Your TraceLoom customer ID
project Yes Your TraceLoom project ID
apiUrl No API base URL (uses default if omitted)

Config Resolution Order

TraceLoom resolves configuration values in this order (first match wins):

  1. Environment variable (TRACELOOM_CUSTOMER_ID, TRACELOOM_PROJECT_ID, TRACELOOM_API_URL)
  2. CLI flag (--customer, --project, --api-url)
  3. Config file (.traceloom.yml, searched up from the current directory)

Exit Codes

Code Meaning
0 All tests passed
1 One or more tests failed
2 Error (API failure, timeout, missing config)

Last updated: April 2026

>