Dd Pup

# pup (Datadog CLI)

Pup CLI for Datadog API operations. Supports OAuth2 and API key auth.

## Quick Reference

| Task | Command |
|------|---------|
| Search error logs | `pup logs search --query "status:error" --from 1h` |
| List monitors | `pup monitors list` |
| Schedule monitor downtime | `pup downtime create --file downtime.json` |
| Find recent slow traces for a service (last 1h) | `pup traces search --query "service:<service-name> @duration:>500ms" --from 1h` |
| List incidents | `pup incidents list --limit 50` |
| Import incident payload | `pup incidents import --file incident.json` |
| Query metrics | `pup metrics query --query "avg:system.cpu.user{*}"` |
| List hosts | `pup infrastructure hosts list --count 50` |
| Check SLOs | `pup slos list` |
| On-call teams | `pup on-call teams list` |
| Triage open critical security signals (last 1h) | `pup security signals list --query "status:open severity:critical" --from 1h --limit 100` |
| Search audit logs | `pup audit-logs search --query "@action:deleted" --from 24h` |
| Audit activity by user | `pup audit-logs search --query "@usr.email:user@example.com" --from 7d` |
| Investigate API key | `pup audit-logs search --query "@metadata.api_key.id:KEY_ID" --from 90d` |
| Check auth | `pup auth status` |
| Token expiry (time left) | `pup auth status` |
| Refresh token | `pup auth refresh` |

## Prerequisites

Install pup using the [setup instructions](https://github.com/datadog-labs/agent-skills/tree/main?tab=readme-ov-file#setup-pup).

## Required Input Resolution

For commands that need specific scope values (`<env>`, `<service-name>`, `<team-id>`, resource IDs), use this order:

1. Check context first (conversation history, prior command output, saved variables).
2. If missing, run a discovery command first (list/search) to get valid values.
3. If still missing or ambiguous, ask the user to confirm the exact value.
4. Then run the target command.
5. Never run commands with unresolved placeholders like `<env>` or `<monitor-id>`.

## Auth

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

**Tokens expire (~1 hour)**. If a command fails with 401/403 mid-conversation:

```bash
pup auth refresh        # Try refresh first
pup auth login          # If refresh fails, full re-auth
```

If Chrome opens the wrong profile/window, use the one-time OAuth URL printed by `pup auth login`
(`If the browser doesn't open, visit: ...`) and open that link manually in the correct account session.

### Headless/CI (no browser)

```bash
# Use env vars or:
export DD_API_KEY=your-api-key
export DD_APP_KEY=your-app-key
export DD_SITE=datadoghq.com    # or datadoghq.eu, etc.
```

## Command Reference

### Monitors
```bash
pup monitors list --limit 10
pup monitors list --tags "env:<env>"
pup monitors get <monitor-id>
pup monitors search --query "<monitor-name>"
pup monitors create --file monitor.json
pup monitors update <monitor-id> --file monitor.json
pup monitors delete <monitor-id>
# No pup monitors mute/unmute commands; use downtime payloads instead.
pup downtime create --file downtime.json
```

### Logs
```bash
pup logs search --query "status:error" --from 1h
pup logs search --query "service:<service-name>" --from 1h --limit 100
pup logs search --query "@http.status_code:5*" --from 24h
pup logs search --query "env:<env> level:error" --from 1h
pup logs aggregate --query "service:<service-name>" --compute count --from 1h
```

### Metrics
```bash
pup metrics query --query "avg:system.cpu.user{*}" --from 1h --to now
pup metrics query --query "sum:trace.express.request.hits{service:<