Lightrace CLI

CLI tool for self-hosting Lightrace — an open-source LLM tracing and observability platform.

---

Spin up the entire Lightrace stack (PostgreSQL, Redis, Backend, Frontend, Caddy gateway) with a single command.

Install

npm (recommended)

npm install -g @lightrace/cli

Homebrew (macOS / Linux)

brew install SKE-Labs/tap/lightrace

Go

go install github.com/SKE-Labs/lightrace-cli@latest

Binary

Download from Releases.

Quick Start

# Initialize project config
lightrace init

# Start all services
lightrace start

# Check status
lightrace status

Open http://localhost:3000 and log in with:

• Email: demo@lightrace.dev
• Password: password

Point your SDK at the server:

export LIGHTRACE_HOST=http://localhost:3000
export LIGHTRACE_PUBLIC_KEY=pk-lt-demo
export LIGHTRACE_SECRET_KEY=sk-lt-demo

Commands

Command	Description
lightrace init	Create .lightrace/config.toml with auto-generated secrets
lightrace start	Pull images and start all services
lightrace stop	Stop and remove all containers
lightrace status	Show service URLs, API keys, health
lightrace db migrate	Run pending database migrations
lightrace db reset	Reset database and re-run migrations
lightrace logs [service]	Tail container logs
lightrace version	Print CLI version

Start Options

lightrace start --exclude frontend    # API-only mode (no dashboard)
lightrace start --ignore-health-check # Start even if health checks fail
lightrace start --pull always         # Always pull latest images (default: missing — use cache if available)
lightrace start --pull never          # Never pull, use cache only (offline mode)

Status Formats

lightrace status              # Pretty table (default)
lightrace status -o json      # JSON output
lightrace status -o env       # Environment variables for SDK

Architecture

The CLI orchestrates 5 Docker containers behind a Caddy reverse proxy on a single port:

:3000 (Caddy)
  ├─ /api/public/*  → Backend  (SDK ingestion, OTLP, tool registry)
  ├─ /trpc/*        → Backend  (tRPC API)
  ├─ /ws            → Backend  (WebSocket subscriptions)
  └─ /*             → Frontend (Dashboard)

Internal services (PostgreSQL, Redis, Backend, Frontend) are not exposed to the host network.

Configuration

lightrace init generates .lightrace/config.toml:

project_id = "my-project"

[gateway]
port = 3000
# domain = "trace.mycompany.com"  # Enables automatic HTTPS

[db]
password = "lightrace"

[auth]
secret = "<auto-generated>"

[api_keys]
public_key = "pk-lt-demo"
secret_key = "sk-lt-demo"

Set a domain for automatic HTTPS via Let's Encrypt (powered by Caddy).

Prerequisites

• Docker (Docker Engine 20.10+)

Related

• Lightrace — the main platform (backend + frontend)
• lightrace-python — Python SDK
• lightrace-js — TypeScript/JavaScript SDK

Development

git clone https://github.com/SKE-Labs/lightrace-cli.git
cd lightrace-cli
go build -o lightrace .
./lightrace --help

License

MIT