CLI Reference

Complete reference for the Spotlight CLI (spotlight-sidecar).

Global Syntax

spotlight-sidecar [command] [options] [arguments]

Commands

run - Run Application with Spotlight

Wraps your application and automatically configures Spotlight.

spotlight-sidecar run [options] [command...]

Examples:

# Auto-detect from package.json
spotlight-sidecar run

# Run specific command
spotlight-sidecar run node server.js
spotlight-sidecar run python manage.py runserver
spotlight-sidecar run go run main.go

# With custom port
spotlight-sidecar run -p 3000 npm start

# With debug logging
spotlight-sidecar run -d node server.js

Behavior:

• Starts Spotlight sidecar server
• Sets SENTRY_SPOTLIGHT environment variable
• Sets SENTRY_TRACES_SAMPLE_RATE=1
• Captures stdout/stderr as logs
• Runs the specified command

Auto-detection: If no command is provided, looks for these scripts in package.json:

1. dev
2. develop
3. serve
4. start

Learn more about run →

---

tail - Stream Events

Streams events from Spotlight to your terminal in real-time.

spotlight-sidecar tail [event-types...] [options]

Event Types:

• errors - Errors and exceptions
• logs - Application logs
• traces - Performance traces
• attachments - File attachments
• all, everything, * - All event types

Examples:

# Stream all events
spotlight-sidecar tail

# Stream only errors
spotlight-sidecar tail errors

# Stream errors and logs
spotlight-sidecar tail errors logs

# Stream with JSON format
spotlight-sidecar tail -f json

# Stream traces with logfmt format
spotlight-sidecar tail traces -f logfmt

# Stream on custom port
spotlight-sidecar tail -p 3000

Behavior:

• Connects to existing sidecar or starts new one
• Streams filtered events to stdout
• Formats output based on -f option

Learn more about tail →

---

mcp - Start MCP Server

Starts Spotlight in MCP (Model Context Protocol) mode for integration with AI coding assistants.

spotlight-sidecar mcp [options]

Examples:

# Start MCP server on default port
spotlight-sidecar mcp

# Start on custom port
spotlight-sidecar mcp -p 3000

# Start with debug logging
spotlight-sidecar mcp -d

Behavior:

• Starts Spotlight sidecar server
• Enables MCP protocol over stdio
• Provides tools for AI assistants to query errors, logs, and traces

Available MCP Tools:

• spotlight.errors.search - Search for errors
• spotlight.logs.search - Search for logs
• spotlight.traces.search - List traces
• spotlight.traces.get - Get trace details

Learn more about MCP →

---

server - Start Standalone Server

Starts the Spotlight sidecar server without any additional modes.

spotlight-sidecar server [options]
spotlight-sidecar [options]  # server is the default command

Examples:

# Start on default port (8969)
spotlight-sidecar server

# Start on custom port
spotlight-sidecar server -p 3000

# Start with debug logging
spotlight-sidecar server -d

# Shorthand (server is default)
spotlight-sidecar
spotlight-sidecar -p 3000

Behavior:

• Starts the sidecar HTTP server
• Listens for events from Sentry SDKs
• Serves the Spotlight UI at http://localhost:PORT
• Streams events via Server-Sent Events (SSE)

---

help - Show Help

Displays help information.

spotlight-sidecar help
spotlight-sidecar --help
spotlight-sidecar -h

Global Options

These options work with all commands:

-p, --port <port>

Specify the port for the sidecar server.

• Type: Number (1-65535 or 0)
• Default: 8969 (for most commands), 0 (for run command)
• Special: 0 = auto-assign random available port

Examples:

spotlight-sidecar -p 3000
spotlight-sidecar --port 9000 tail errors
spotlight-sidecar run -p 0 npm start  # Random port

-d, --debug

Enable debug logging for troubleshooting.

• Type: Boolean
• Default: false

Examples:

spotlight-sidecar -d
spotlight-sidecar --debug tail logs
spotlight-sidecar run -d node server.js

Output includes:

• Detailed server startup information
• Connection status
• Event processing details
• SDK communication logs

-h, --help

Show help message and exit.

Examples:

spotlight-sidecar -h
spotlight-sidecar --help

Command-Specific Options

Tail Command Options

-f, --format <format>

Specify output format for events.

• Type: String
• Options: human, logfmt, json, md
• Default: human

Examples:

spotlight-sidecar tail -f json
spotlight-sidecar tail --format logfmt errors
spotlight-sidecar tail errors logs -f md

Formats:

• human - Colored, human-readable (default)
• logfmt - Machine-readable key-value pairs
• json - Structured JSON (one per line)
• md - Markdown format

Environment Variables

SPOTLIGHT_DEBUG

Enable debug logging (alternative to -d flag).

export SPOTLIGHT_DEBUG=1
spotlight-sidecar tail

SENTRY_SPOTLIGHT

Set by run command to tell SDKs where to send events.

# Automatically set by spotlight-sidecar run
SENTRY_SPOTLIGHT=http://localhost:8969/stream

SENTRY_TRACES_SAMPLE_RATE

Set by run command to enable 100% trace sampling.

# Automatically set by spotlight-sidecar run
SENTRY_TRACES_SAMPLE_RATE=1

Exit Codes

• 0 - Success
• 1 - General error (invalid arguments, connection failed, etc.)
• 130 - Interrupted by user (SIGINT/Ctrl+C)

Configuration Files

Spotlight CLI does not use configuration files. All configuration is done via command-line arguments and environment variables.

Common Patterns

Development Workflow

# Terminal 1: Run your app with Spotlight
spotlight-sidecar run

# Terminal 2: Monitor specific events
spotlight-sidecar tail errors logs

# Browser: View in UI
open http://localhost:8969

CI/CD Integration

# Capture events during tests
spotlight-sidecar tail -f json > events.json &
SPOTLIGHT_PID=$!

# Run tests
spotlight-sidecar run npm test

# Cleanup
kill $SPOTLIGHT_PID

Multi-Service Setup

# Service 1 (backend)
spotlight-sidecar run -p 8969 npm run dev:backend

# Service 2 (frontend - connects to same sidecar)
spotlight-sidecar run -p 8969 npm run dev:frontend

Log Aggregation

# Stream to file with logfmt
spotlight-sidecar tail -f logfmt >> spotlight.log

# Stream to file with JSON
spotlight-sidecar tail -f json | jq . >> spotlight.json

Version

To check the installed version:

spotlight-sidecar --version
# or check package version
npm list -g @spotlightjs/sidecar

Package Information

• Package: @spotlightjs/sidecar
• Binary: spotlight-sidecar
• Minimum Node Version: 20.0.0

Related Documentation

• Run Command Guide - Detailed guide for running applications
• Tail Command Guide - Detailed guide for streaming events
• MCP Integration - Using Spotlight with AI coding assistants
• Sidecar Documentation - Understanding the sidecar server