Cased CLI

Query telemetry and AI agent sessions from your terminal. Designed for use with Claude Code.

Installation

uv tool install cased-cli

Or with pip:

pip install cased-cli

Configuration

Browser Authentication (Recommended)

cased configure

This will:

1. Display a verification code (e.g., ABCD-1234)
2. Open your browser to https://app.cased.com/cli/verify
3. Enter the code and authorize access
4. Save credentials to ~/.config/cased/config.json

Environment Variables (Alternative)

For CI/CD or scripts, set your API key directly:

export CASED_API_KEY=your_api_key_here
export CASED_API_URL=https://app.cased.com  # optional, defaults to this

Get an API key from: https://app.cased.com/settings/api

Usage

Query Errors

# Recent errors
cased errors --since 24h

# Search for specific errors
cased errors --search "KeyError" --level error

# Output as JSON (for piping to other tools)
cased errors --since 1h --json

Query Traces

# Recent traces
cased traces --since 1h

# Filter by service
cased traces --service demo-web --status error

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

Query Metrics

# Recent metrics
cased metrics --since 1h

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

# Filter by metric type
cased metrics --metric cpu_percent --namespace default

Overview

# Get statistics summary
cased stats

# List clusters
cased clusters

Agent Sessions

# List recent sessions
cased sessions --since 24h

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

# Filter by type
cased sessions --type root_cause_analysis

# Get session details
cased session <session_id>

# View session logs and conversation
cased session <session_id> --logs
cased session <session_id> --conversation

Source Maps

Upload source maps to de-minify JavaScript stack traces:

# Upload source maps for a release
cased sourcemaps upload -p my-project -r v1.2.3 dist/*.map

# List uploaded source maps
cased sourcemaps list -p my-project

# Delete source maps for a release
cased sourcemaps delete -p my-project -r v1.2.3

Upload Documentation

Upload documents to the Cased knowledge base to help the AI understand your organization.

# Upload a file (title auto-generated from filename)
cased docs upload README.md

# Upload with custom title
cased docs upload --title "Deployment Guide" docs/deploy.md

# Upload from stdin
cat architecture.md | cased docs upload --title "Architecture" -

# Upload with AI cleanup (formats and structures content)
cased docs upload --cleanup meeting-notes.txt

# Upload conversation logs
cased docs upload --format conversation --cleanup session.log

With Claude Code

Skill (Recommended)

Copy the .claude/skills/cased directory to your project. Claude will automatically use the Cased CLI when you ask about errors, traces, metrics, or agent sessions.

Slash Command

Add to your project's .claude/commands/telemetry.md:

Query telemetry using the Cased CLI. The user wants to investigate errors, traces, metrics, or agent sessions.

Available commands:
- `cased errors --since <time> [--level <level>] [--search <term>]`
- `cased traces --since <time> [--service <name>] [--status <ok|error>]`
- `cased metrics --since <time> [--pod <name>] [--metric <name>]`
- `cased sessions --since <time> [--status <status>]`
- `cased session <id> [--logs] [--conversation]`
- `cased stats` - Get overview
- `cased clusters` - List clusters

Use `--json` flag when you need to process the output programmatically.

Then: /telemetry investigate the errors from the last hour

Docs Upload Skill

Add to your project's .claude/skills/upload-docs.md:

Upload documentation to Cased knowledge base using the CLI.

Use `cased docs upload` to add documents that help the AI understand your codebase.

Commands:
- `cased docs upload <file>` - Upload a file (title from filename)
- `cased docs upload --title "Title" <file>` - Upload with custom title
- `cat <file> | cased docs upload --title "Title" -` - Upload from stdin
- `cased docs upload --cleanup <file>` - Upload with AI formatting
- `cased docs upload --format conversation <file>` - Upload conversation logs

Examples:
- Upload README: `cased docs upload README.md`
- Upload with cleanup: `cased docs upload --cleanup --title "Meeting Notes" notes.txt`

Then ask Claude: "Upload the architecture docs to Cased"