Cased CLI

Query telemetry, monitor LLM usage, and analyze performance from your terminal

The Cased CLI provides command-line access to your observability data. Query errors, traces, metrics, and LLM usage directly from your terminal.

Installation

uv pip install cased-cli

Configuration

Web Authentication (Recommended)

The easiest way to authenticate is via your browser:

cased configure

This will:

1. Open your browser to the Cased login page
2. You click “Authorize” after logging in
3. CLI saves your token to ~/.config/cased/config.json

Works in SSH sessions too—just copy the URL from the terminal.

Environment Variables

Alternatively, set your API key as an environment variable:

export CASED_API_KEY=your_api_key_here

Get your API key from Settings.

Optionally set a custom API URL (defaults to https://app.cased.com):

export CASED_API_URL=https://app.cased.com

Managing Authentication

# Check current auth status
cased configure

# Re-authenticate (get a new token)
cased configure --force

# Log out and remove saved credentials
cased logout

Quick Start

# Follow logs in real-time
cased logs -f

# View recent errors
cased errors --since 1h

# Check trace performance
cased traces --service api --status error

# Monitor LLM costs
cased llm cost --since 24h

# Find slow spans
cased perf slow --threshold 500

# Get overall stats
cased stats

Command Groups

Command	Description
cased logs	Query application logs
cased errors	Query error events
cased traces	Query distributed traces
cased metrics	Query container metrics
cased stats	Overall telemetry statistics
cased clusters	List clusters with telemetry
cased sessions	List AI agent sessions
cased session	Get session details
cased sourcemaps	Manage source maps
cased perf	Performance analysis
cased llm	LLM monitoring

Global Options

All commands support:

Option	Description
--json	Output as JSON instead of formatted tables
--help	Show help for a command

---

Application Logs

cased logs

Query and tail application logs in real-time.

# Last 100 logs (default)
cased logs

# Last 50 logs
cased logs --tail 50

# Follow logs in real-time (like docker logs -f)
cased logs -f

# Follow with initial context
cased logs -f --tail 20

# Filter by level
cased logs -l error
cased logs -l warn

# Filter by service
cased logs -s api-server

# Search in messages
cased logs -q "timeout"
cased logs -q "connection refused" --since 1h

# Show full timestamps
cased logs -t

# Combine filters
cased logs -f -l error -s api-server

Options:

Option	Default	Description
--tail, -n	100	Number of lines to show
--follow, -f	-	Follow logs in real-time
--timestamps, -t	-	Show full timestamps
--since	1h	Time range (1h, 24h, 7d)
--level, -l	-	Filter by level (trace, debug, info, warn, error, fatal)
--service, -s	-	Filter by service name
--search, -q	-	Search in log messages

---

Error Tracking

cased errors

Query error events from your applications.

# Recent errors (last 24h)
cased errors

# Errors in the last hour
cased errors --since 1h

# Filter by severity
cased errors --level error
cased errors --level fatal

# Search in exception type/value
cased errors --search "KeyError"
cased errors --search "connection refused"

# Filter by project
cased errors --project my-project-id

# Output as JSON
cased errors --since 1h --json

Options:

Option	Default	Description
--since	24h	Time range (1h, 24h, 7d)
--level	-	Filter by level (error, warning, fatal)
--search	-	Search in exception type/value
--project	-	Filter by project ID
--limit	50	Max results

---

Distributed Tracing

cased traces

Query distributed traces and spans.

# Recent traces
cased traces --since 1h

# Filter by service
cased traces --service api
cased traces --service worker

# Filter by status
cased traces --status error
cased traces --status ok

# Get all spans for a specific trace
cased traces --trace-id abc123def456

# Filter by cluster
cased traces --cluster prod-us-east

Options:

Option	Default	Description
--since	1h	Time range
--service	-	Filter by service name
--status	-	Filter by status (ok, error)
--trace-id	-	Get all spans for a trace
--cluster	-	Filter by cluster ID
--limit	50	Max results

---

Metrics

cased metrics

Query container metrics from your clusters.

# Recent metrics
cased metrics --since 1h

# Filter by pod
cased metrics --pod my-pod-abc123

# Filter by metric type
cased metrics --metric cpu_percent
cased metrics --metric memory_bytes

# Filter by namespace
cased metrics --namespace production

Options:

Option	Default	Description
--since	1h	Time range
--cluster	-	Filter by cluster ID
--namespace	-	Filter by namespace
--pod	-	Filter by pod name
--metric	-	Filter by metric name
--limit	50	Max results

cased stats

Get overall telemetry statistics.

cased stats
cased stats --json

cased clusters

List clusters sending telemetry data.

cased clusters
cased clusters --json

---

Agent Sessions

cased sessions

List AI agent sessions.

# Recent sessions
cased sessions --since 24h

# Filter by status
cased sessions --status completed
cased sessions --status failed
cased sessions --status agent_running

# Filter by type
cased sessions --type root_cause_analysis
cased sessions --type deploy_monitor

Options:

Option	Default	Description
--since	24h	Time range
--status	-	Filter by status
--type	-	Filter by session type
--limit	20	Max results

cased session <session_id>

Get details for a specific session.

# Basic details
cased session abc123

# Include execution logs
cased session abc123 --logs

# Include conversation history
cased session abc123 --conversation

# Full JSON output
cased session abc123 --json

---

Source Maps

Manage source maps for JavaScript error de-minification.

cased sourcemaps upload

Upload source maps for a release.

# Upload source maps
cased sourcemaps upload -p my-app -r v1.2.3 dist/*.map

# With URL prefix
cased sourcemaps upload -p my-app -r v1.2.3 --url-prefix "~/" build/*.map

# Using git SHA as release
cased sourcemaps upload -p my-app -r $GIT_SHA dist/*.map

cased sourcemaps list

List uploaded source maps.

# All source maps for a project
cased sourcemaps list -p my-app

# Filter by release
cased sourcemaps list -p my-app -r v1.2.3

cased sourcemaps delete

Delete source maps for a release.

# Interactive confirmation
cased sourcemaps delete -p my-app -r v1.2.3

# Skip confirmation
cased sourcemaps delete -p my-app -r v1.2.3 -y

---

Performance Analysis

Analyze trace performance, detect bottlenecks, and find regressions.

cased perf slow

Find spans exceeding a duration threshold.

# Find slow spans (>500ms default)
cased perf slow --since 1h

# Custom threshold (1 second)
cased perf slow --threshold 1000

# Filter by service
cased perf slow --service api --since 24h

Options:

Option	Default	Description
--since	1h	Time range
--threshold	500	Minimum duration in ms
--service	-	Filter by service
--limit	50	Max results

cased perf latency

View latency percentiles (p50, p95, p99).

# By service
cased perf latency --since 1h

# By endpoint
cased perf latency --service api --group-by endpoint

# Both service and endpoint
cased perf latency --group-by both

Options:

Option	Default	Description
--since	1h	Time range
--service	-	Filter by service
--group-by	service	Group by: service, endpoint, both

cased perf n1

Detect N+1 query patterns.

# Find N+1 patterns
cased perf n1 --since 1h

# Require more repetitions
cased perf n1 --min-count 10

Options:

Option	Default	Description
--since	1h	Time range
--min-count	5	Minimum repetitions to flag
--limit	50	Max results

cased perf breakdown

Get service time breakdown for a trace.

cased perf breakdown <trace_id>

Shows where time was spent across different services in a trace.

cased perf regression

Detect performance regressions by comparing time periods.

# Compare last day to last week
cased perf regression --service api

# Custom periods
cased perf regression --service api --baseline 7d --compare 1d

# Filter by endpoint
cased perf regression --service api --endpoint /api/users

Options:

Option	Default	Description
--service	(required)	Service to analyze
--endpoint	-	Filter by endpoint
--baseline	7d	Baseline period
--compare	1d	Comparison period

cased perf summary

Get overall performance summary.

cased perf summary --since 1h
cased perf summary --since 24h

---

LLM Monitoring

Track LLM usage, costs, latency, and errors.

cased llm usage

View token usage statistics.

# Usage by model
cased llm usage --since 24h

# Group by provider
cased llm usage --group-by provider

# Filter by model
cased llm usage --model gpt-4o

Options:

Option	Default	Description
--since	24h	Time range
--model	-	Filter by model
--provider	-	Filter by provider
--group-by	model	Group by: model, provider, both
--limit	50	Max results

cased llm cost

View estimated LLM costs.

# Cost by model
cased llm cost --since 24h

# Filter by model
cased llm cost --model claude-sonnet-4

# Group by provider
cased llm cost --group-by provider

cased llm latency

View LLM latency percentiles.

cased llm latency --since 24h
cased llm latency --model gpt-4o

cased llm errors

View LLM error statistics.

# Error rates
cased llm errors --since 24h

# Filter by model
cased llm errors --model gpt-4o

cased llm summary

Get overall LLM usage summary.

cased llm summary --since 24h
cased llm summary --since 7d

Shows total calls, tokens, estimated costs, latency, and error rates.

cased llm sessions

View per-session LLM usage for multi-turn conversations.

# Sessions by cost (most expensive first)
cased llm sessions --sort-by cost

# Sessions by token usage
cased llm sessions --sort-by tokens

# Recent sessions
cased llm sessions --sort-by created --limit 10

Options:

Option	Default	Description
--since	24h	Time range
--sort-by	created	Sort by: cost, calls, tokens, created
--limit	20	Max sessions

---

JSON Output

All commands support --json for machine-readable output:

# Pipe to jq for filtering
cased errors --since 1h --json | jq '.events[] | select(.level == "fatal")'

# Save to file
cased llm cost --since 7d --json > weekly-costs.json

# Use in scripts
COST=$(cased llm summary --json | jq -r '.estimated_cost_usd')
echo "Weekly LLM cost: \$${COST}"

Time Ranges

All --since options accept:

Format	Example	Description
Hours	1h, 6h, 24h	Last N hours
Days	1d, 7d, 30d	Last N days

Exit Codes

Code	Description
0	Success
1	Error (API error, connection error, invalid input)