dd-pup

name	dd-pup
description	Datadog CLI (Go). OAuth2 auth with token refresh.
metadata	{"version":"1.0.0","author":"datadog-labs","repository":"https://github.com/datadog-labs/agent-skills","tags":"datadog,cli,dd-pup,pup","alwaysApply":"false"}

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

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

Auth

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:

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

Headless/CI (no browser)

# 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

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

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

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

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

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

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

SLOs

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

Synthetics

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

On-Call

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

Hosts / Infrastructure

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

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

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

Users / Teams

pup users list
pup teams list

Security

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

Service Catalog

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

Notebooks

pup notebooks list
pup notebooks get --id 12345

Workflows

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

Subcommand Discovery

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

go install github.com/DataDog/pup@latest

Verify Installation

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

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):

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

# Then reload
source ~/.zshrc

For bash:

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

# Then reload
source ~/.bashrc

For 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:

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:

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

Or create an alias:

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