pup

What this skill does

# Pup — Datadog CLI

## Overview

Pup is Datadog's AI-agent-ready CLI covering 49 command groups and 300+ subcommands across the full Datadog platform: metrics, logs, monitors, APM, traces, dashboards, SLOs, incidents, security, infrastructure, RUM, CI/CD, costs, and more.

Key traits:
- **Self-discoverable** — `pup --help` and `pup agent schema` return structured JSON schemas
- **Agent mode auto-detected** — structured JSON output in Claude Code (no setup needed)
- **OAuth2 + API key auth** — secure browser-based login or environment variable fallback
- **Structured output** — JSON (default), YAML, or table formats

## Prerequisites

```bash
brew tap datadog-labs/pack
brew install pup
```

Or build from source:

```bash
git clone https://github.com/datadog-labs/pup.git && cd pup
cargo build --release
cp target/release/pup /usr/local/bin/pup
```

Verify installation:

```bash
pup --version
```

## Authentication

### OAuth2 (Preferred)

OAuth2 provides secure, browser-based auth with automatic token refresh. Tokens are stored in your OS keychain.

```bash
pup auth login           # Opens browser for OAuth2 flow
pup auth status          # Check token validity
pup auth refresh         # Refresh expired token (no browser needed)
pup auth logout          # Clear credentials
```

**Tokens expire after ~1 hour.** If a command returns 401/403:

```bash
pup auth refresh         # Try this first
pup auth login           # Full re-auth if refresh fails
```

### API Keys (Legacy / CI)

For headless environments or when OAuth2 is unavailable:

```bash
export DD_API_KEY="your-api-key"
export DD_APP_KEY="your-app-key"
export DD_SITE="datadoghq.com"       # Default; change for EU/other sites
```

### Authentication Priority

1. `DD_ACCESS_TOKEN` — Stateless bearer token (highest priority)
2. OAuth2 tokens (from `pup auth login`)
3. API keys (`DD_API_KEY` + `DD_APP_KEY`)

### Datadog Sites

| Site | `DD_SITE` value |
|------|-----------------|
| US1 (default) | `datadoghq.com` |
| US3 | `us3.datadoghq.com` |
| US5 | `us5.datadoghq.com` |
| EU1 | `datadoghq.eu` |
| AP1 | `ap1.datadoghq.com` |
| US1-FED | `ddog-gov.com` |

## Agent Mode

Agent mode is **auto-detected** in Claude Code via the `CLAUDE_CODE` environment variable. No setup required.

What changes in agent mode:

| Behavior | Human Mode | Agent Mode |
|----------|-----------|------------|
| `--help` output | Standard text | Structured JSON schema |
| Confirmations | Interactive prompt | Auto-approved |
| Error format | Human text | Structured JSON with error codes and suggestions |
| API responses | Raw data | Envelope with metadata (count, truncation, warnings) |

### Schema Discovery

```bash
pup --help                    # Full JSON schema (auto in agent mode)
pup logs --help               # Domain-specific schema
pup agent schema              # Explicit full schema (works in any mode)
pup agent schema --compact    # Minimal schema (fewer tokens)
pup agent guide               # Full steering guide (markdown)
```

Use `pup agent schema` when unsure about a command's flags or syntax.

## Command Patterns

All commands follow a consistent structure:

```bash
pup <domain> <action> [flags]              # Simple commands
pup <domain> <subgroup> <action> [flags]   # Nested commands
```

### CRUD Operations

```bash
pup <resource> list [--filters]            # List/search
pup <resource> get <id>                    # Get by ID
pup <resource> create [--file=data.json]   # Create from JSON
pup <resource> update <id> [--file=...]    # Update
pup <resource> delete <id> [--yes]         # Delete (--yes skips confirmation)
```

## Quick Reference

### Core Observability

| Task | Command |
|------|---------|
| Search error logs | `pup logs search --query="status:error" --from=1h` |
| Count logs by service | `pup logs aggregate --query="*" --from=1h --compute="count" --group-by="service"` |
| P99 latency by service | `pup logs aggregate --query="env:prod" --from=30m --compute="percentile(@duration, 99)" --group-by="service"` |
| Query CPU metrics | `pup metrics query --query="avg:system.cpu.user{*}" --from=1h` |
| List metrics | `pup metrics list --filter="system.*"` |
| Search traces | `pup traces search --query="service:api AND @duration:>1000000000" --from=1h` |
| List APM services | `pup apm services list --env=production` |

### Monitoring & Alerting

| Task | Command |
|------|---------|
| List monitors | `pup monitors list` |
| Filter by tags | `pup monitors list --tags="env:production"` |
| Search monitors | `pup monitors search --query="status:Alert"` |
| List dashboards | `pup dashboards list` |
| Get dashboard URL | `pup dashboards url abc-123 --from=now-1w --to=now --live=true` |
| List SLOs | `pup slos list` |
| SLO status | `pup slos status slo-123 --from=30d --to=now` |
| Synthetics tests | `pup synthetics tests list` |

### Incidents & Operations

| Task | Command |
|------|---------|
| List incidents | `pup incidents list` |
| Get incident | `pup incidents get <incident-id>` |
| List events | `pup events list --from=4h` |
| On-call teams | `pup on-call teams list` |
| Service context | `pup idp assist my-service` |
| Service dependencies | `pup idp deps my-service` |
| Who owns a service | `pup idp owner my-service` |

### Security

| Task | Command |
|------|---------|
| Security signals | `pup security signals list --from=24h` |
| Security rules | `pup security rules list` |
| Critical findings | `pup security findings search --query="@severity:critical"` |
| Audit logs | `pup audit-logs list --from=7d` |

### Infrastructure

| Task | Command |
|------|---------|
| List hosts | `pup infrastructure hosts list` |
| Filter hosts | `pup infrastructure hosts list --filter="env:production"` |
| Host tags | `pup tags list` |
| Containers | `pup containers list` |
| Fleet agents | `pup fleet agents list --filter="hostname:my-host"` |

### Live Debugger

| Task | Command |
|------|---------|
| Find probe-able methods | `pup symdb search --service=my-svc --query=MyController --view=probe-locations` |
| Create log probe | `pup debugger probes create --service=my-svc --env=prod --probe-location="com.example.MyClass:myMethod" --capture="request.id" --ttl=1h` |
| Watch probe events | `pup debugger probes watch <probe-id> --fields="message,captures,timestamp" --limit=10` |

## Output Formats

```bash
pup monitors list --output=json    # JSON (default, best for agents)
pup monitors list --output=table   # Human-readable table
pup monitors list --output=yaml    # YAML
pup monitors list --fields="id,name,status"  # Custom field selection
```

## Time Range Formats

All `--from` and `--to` flags accept these formats:

| Format | Example |
|--------|---------|
| Relative short | `1h`, `30m`, `7d`, `5s`, `1w` |
| Relative long | `5min`, `2hours`, `3days` |
| With spaces | `"5 minutes"`, `"2 hours"` |
| RFC3339 | `2024-01-01T00:00:00Z` |
| Unix ms | `1704067200000` |
| Keyword | `now` |

## Query Syntax

### Logs

```
status:error                        # Filter by status
service:web-app                     # Filter by service
@user.id:12345                      # Custom attribute (@ prefix)
host:i-*                            # Wildcard matching
"exact error message"               # Exact phrase
status:error AND service:web        # Boolean AND
status:error OR status:warn         # Boolean OR
-status:info                        # Negation
@http.status_code:[400 TO 599]     # Numeric range
```

### Metrics

```
avg:system.cpu.user{env:prod} by {host}       # CPU by host
sum:trace.servlet.request.hits{service:web}   # Request count
max:system.mem.used{*} by {host}              # Max memory
```

### APM / Traces

**CRITICAL: Durations are in NANOSECONDS**
- 1ms = 1,000,000 ns
- 1s = 1,000,000,000 ns
- 5s = 5,000,000,000 ns

```
service:api-gateway                            # Filter by service
resource_name:/api/v1/users                    # Filter by endpoint
@duration:>5000000000                          # Duration > 5s