CLI Reference
The la CLI gives you terminal-first access to your observability data. Query spans, stream live logs, fetch trace flamegraphs, and upload source maps — all from your terminal.
npm install -g @lightarch/clila login
Authenticate the CLI by opening your browser (same pattern as wrangler login):
la loginA browser window opens to lightarch-dashboard.pages.dev/cli-auth. Sign in with your email and password. The terminal polls until authentication completes, then saves your session token and DSN to the local config file.
Screenshot needed
Terminal showing 'la login' output: '◈ Lightarch Login', 'Opening your browser to complete sign-in...', URL shown, spinner '⠋ Waiting for browser sign-in…', then '✓ Authenticated successfully!', 'Tenant: tenant-d836406c', 'DSN: la_live_4d87ed83...', '→ Try it: la query SELECT * FROM recent_spans LIMIT 10'
la init
Initialise a project — detects your runtime and writes an OTel config file:
la init --dsn la_live_YOUR_TOKEN_HERECreates eo.config.js (Node.js), eo_config.py (Python), or eo.go (Go).
la query
Run any SELECT SQL against your hot index (last 48h of spans + metrics_samples):
# Table output (default)
la query "SELECT service, severity, body FROM recent_spans WHERE severity = 'ERROR' ORDER BY timestamp DESC LIMIT 10"
# JSON output
la query "SELECT * FROM recent_spans LIMIT 5" --jsonScreenshot needed
Terminal showing 'la query' table output: header row 'service | severity | body', divider line, rows showing payment-service | ERROR | Stripe error: card_declined, api-gateway | ERROR | Unhandled exception. Footer: '2 rows'.
Useful queries
# Error rate by service
la query "SELECT service, COUNT(*) as total, SUM(is_error) as errors, ROUND(SUM(is_error)*100.0/COUNT(*),1) as pct FROM recent_spans GROUP BY service ORDER BY pct DESC"
# Slowest spans last hour
la query "SELECT service, span_name, duration_ms, body FROM recent_spans ORDER BY duration_ms DESC LIMIT 10"
# Severity breakdown
la query "SELECT severity, COUNT(*) as n FROM recent_spans GROUP BY severity ORDER BY n DESC"
# Latest metrics
la query "SELECT metric_name, service, ROUND(p99,1) as p99_ms FROM metrics_samples ORDER BY timestamp DESC LIMIT 10"la trace fetch
Fetch a trace by ID and render it as an ASCII flamegraph:
la trace fetch aabb1122ccdd3344
# Raw JSON (for piping to jq)
la trace fetch aabb1122ccdd3344 --jsonScreenshot needed
Terminal output of 'la trace fetch': 'Trace: aabb1122ccdd3344 | Total: 342ms | Status: ERROR | Source: api-gateway'. Tree showing '├── api-gateway [████████░░] [142ms] ✓', '│ ├── user-service [████░░░░] [98ms] ✓', '│ └── postgres [██░░░░░░] [45ms] ✓', '└── payment-svc [████████████████████] [342ms] ✗'.
la logs tail
Stream live spans for a service — stops with Ctrl+C:
la logs tail --service api-gateway
# Errors only
la logs tail --service payment-service --errors-onlyScreenshot needed
Terminal showing live tail output: rows of '08:32:11 ✓ api-gateway 200 12ms trace:aabb1122', '08:32:14 ✗ payment-service 500 342ms trace:deadbeef', new rows appearing in real time.
la logs search
Full-text search against cold storage (R2 SQL):
la logs search "card declined" --last 7d
la logs search "timeout" --service api-gateway --last 24hla upload-maps
Upload source maps so Lightarch can resolve minified stack frames back to original source:
la upload-maps --release v1.2.3 ./dist
la upload-maps --release $(git rev-parse --short HEAD) ./dist--help for options: la logs tail --help