Metadata-Version: 2.4
Name: cased-cli
Version: 0.1.1
Summary: CLI for Cased telemetry - query errors, metrics, and traces
Project-URL: Homepage, https://github.com/cased/cli
Project-URL: Repository, https://github.com/cased/cli
Project-URL: Issues, https://github.com/cased/cli/issues
Author-email: Ted Nyman <ted@cased.com>
License: MIT
License-File: LICENSE
Keywords: cli,errors,metrics,observability,telemetry,traces
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.25
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# 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

Set your API key:

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

Get your 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
```

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