cased-cli 0.3.1
CLI for Cased telemetry - query errors, metrics, and traces
License: MIT
Requires Python: >=3.10
Keywords: cli, errors, metrics, observability, telemetry, traces

# Cased CLI

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

## Installation

```bash
uv tool install cased-cli
```

Or with pip:
```bash
pip install cased-cli
```

## Configuration

### Browser Authentication (Recommended)

```bash
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:

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Get statistics summary
cased stats

# List clusters
cased clusters
```

### Agent Sessions

```bash
# 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:

```bash
# 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.

```bash
# 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`:

```markdown
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`:

```markdown
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"