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" --duration 1h`   |
| List monitors         | `pup monitors list`                                      |
| Mute a monitor        | `pup monitors mute --id 123 --duration 1h`               |
| Find slow traces      | `pup apm traces list --service api --min-duration 500ms` |
| List active incidents | `pup incidents list --status active`                     |
| Create incident       | `pup incidents create --title "Issue" --severity SEV-2`  |
| Query metrics         | `pup metrics query --query "avg:system.cpu.user{*}"`     |
| List hosts            | `pup hosts list`                                         |
| Check SLOs            | `pup slos list`                                          |
| Who's on call         | `pup on-call who --team my-team`                         |
| Security signals      | `pup security signals list --severity critical`          |
| Check auth            | `pup auth status`                                        |
| Refresh token         | `pup auth refresh`                                       |

## Prerequisites

```bash
# Install pup
go install github.com/datadog-labs/pup@latest
export PATH="$HOME/go/bin:$PATH"
```

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

### 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:prod"
pup monitors get --id 12345
pup monitors mute --id 12345 --duration 1h
pup monitors unmute --id 12345
pup monitors create --name "High CPU" --type "metric alert" \
  --query "avg(last_5m):avg:system.cpu.user{*} > 80" \
  --message "CPU high @slack-ops"
```

### Logs

```bash
pup logs search --query "status:error" --duration 1h
pup logs search --query "service:payment-api" --duration 1h --limit 100
pup logs search --query "@http.status_code:5*" --duration 24h
pup logs search --query "env:prod level:error" --duration 1h --json
```

### Metrics

```bash
pup metrics query --query "avg:system.cpu.user{*}" --duration 1h
pup metrics query --query "sum:trace.express.request.hits{service:api}" --duration 1h
pup metrics list --filter "system.*"
```

### APM / Traces

```bash
pup apm services list
pup apm traces list --service my-service --duration 1h
pup apm traces list --service api --min-duration 500ms --duration 1h
pup apm traces list --service api --status error --duration 1h
pup apm traces get abc123def456
```

### Incidents

```bash
pup incidents list --status active
pup incidents list --status resolved --duration 7d
pup incidents create --title "API Degradation" --severity SEV-2
pup incidents update --id abc-123 --status stable
pup incidents resolve --id abc-123
```

### Dashboards

```bash
pup dashboards list
pup dashboards list --tags "team:platform"
pup dashboards get --id abc-123
pup dashboards create --title "My Dashboard" --description "..." --widgets '[...]'
```

### SLOs

```bash
pup slos list
pup slos get --id slo-123
pup slos history --id slo-123 --duration 30d
```

### Synthetics

```bash
pup synthetics list
pup synthetics results --test-id abc-123
pup synthetics trigger --test-id abc-123
```

### On-Call

```bash
pup on-call teams list
pup on-call schedules list
pup on-call who --team platform-team
```

### Hosts / Infrastructure

```bash
pup hosts list --limit 50
pup hosts list --filter "env:prod"
pup hosts mute --hostname web-01 --duration 1h
pup hosts get --hostname web-01
```

### Events

```bash
pup events list --duration 24h
pup events list --tags "source:deploy"
pup events post --title "Deploy started" --text "v1.2.3" --tags "env:prod"
```

### Downtimes

```bash
pup downtime list
pup downtime create --scope "env:staging" --duration 2h --message "Maintenance"
pup downtime cancel --id 12345
```

### Users / Teams

```bash
pup users list
pup teams list
```

### Security

```bash
pup security signals list --duration 24h
pup security signals list --severity critical
```

### Service Catalog

```bash
pup services list
pup services get --name payment-api
```

### Notebooks

```bash
pup notebooks list
pup notebooks get --id 12345
```

### Workflows

```bash
pup workflows list
pup workflows trigger --id workflow-123 --input '{"key": "value"}'
```

## Subcommand Discovery

```bash
pup --help              # List all commands
pup <command> --help    # Command-specific help
```

## Error Handling

| Error            | Cause             | Fix                       |
| ---------------- | ----------------- | ------------------------- |
| 401 Unauthorized | Token expired     | `pup auth refresh`        |
| 403 Forbidden    | Missing scope     | Check app key permissions |
| 404 Not Found    | Wrong ID/resource | Verify resource exists    |
| Rate limited     | Too many requests | Add delays between calls  |

## Install

```bash
go install github.com/DataDog/pup@latest
```

### Verify Installation

```bash
# Check if pup is in PATH
which pup

# If not found, check if it was installed
ls ~/go/bin/pup
```

### PATH Troubleshooting

If `pup` is installed but `which pup` returns nothing, Go's bin directory isn't in your PATH.

**Check where pup is:**

```bash
ls ~/go/bin/pup           # Standard location
ls $GOPATH/bin/pup        # If GOPATH is set
ls $GOBIN/pup             # If GOBIN is set
```

**Add to PATH (pick your shell):**

For **zsh** (macOS default):

```bash
# Add this line to ~/.zshrc
export PATH="$HOME/go/bin:$PATH"

# Then reload
source ~/.zshrc
```

For **bash**:

```bash
# Add this line to ~/.bashrc or ~/.bash_profile
export PATH="$HOME/go/bin:$PATH"

# Then reload
source ~/.bashrc
```

For **fish**:

```fish
# Add this line to ~/.config/fish/config.fish
fish_add_path $HOME/go/bin

# Or set permanently
set -Ux fish_user_paths $HOME/go/bin $fish_user_paths

# Then reload
source ~/.config/fish/config.fish
```

**Verify:**

```bash
which pup        # Should show path
pup --version    # Should show version
```

### Alternative: Full Path

If you don't want to modify PATH, use the full path:

```bash
~/go/bin/pup auth login
~/go/bin/pup monitors list
```

Or create an alias:

```bash
alias pup="$HOME/go/bin/pup"
```

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