Pup

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

brew tap datadog-labs/pack
brew install pup

Or build from source:

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

Verify installation:

pup --version

Authentication

OAuth2 (Preferred)

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

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:

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:

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

Agent Mode

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

What changes in agent mode:

Schema Discovery

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:

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

CRUD Operations

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

Monitoring & Alerting

Incidents & Operations

Security

Infrastructure

Live Debugger

Output Formats

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:

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 (nanoseconds!)
status:error                                   # Error spans only
env:production                                 # Filter by environment

Error Handling

Best Practices

1. Always specify --from — most commands default to 1h but be explicit
2. Start narrow, widen later — begin with 1h, expand to 24h/7d only if needed
3. Filter at the API level — use --tags, --query, --name flags instead of fetching everything
4. Use aggregate for counts — pup logs aggregate --compute=count, not fetch-all-and-count
5. APM durations are nanoseconds — 1s = 1,000,000,000 (not seconds or milliseconds)
6. Chain queries — aggregate first to find patterns, then search for specifics
7. Use pup agent schema when unsure about a command's flags

Anti-Patterns

1. Don't omit --from on time-series queries — you'll get unexpected ranges or errors
2. Don't use --limit=1000 first — start small (--limit=20) and refine
3. Don't list all monitors without filters in large orgs (>10k monitors)
4. Don't assume durations are in seconds — APM uses nanoseconds
5. Don't fetch raw logs to count them — use pup logs aggregate --compute=count
6. Don't retry 401/403 errors — re-authenticate or check permissions instead
7. Don't use --from=30d unless you specifically need a month of data

Common Workflows

Error Investigation

# 1. Get error counts by service
pup logs aggregate --query="status:error" --from=1h --compute="count" --group-by="service"

# 2. Drill into affected service
pup logs search --query="status:error AND service:<name>" --from=1h --limit=20

# 3. Check monitors for that service
pup monitors list --tags="service:<name>"

# 4. Check recent events
pup events list --from=4h

Performance Investigation

# 1. Check service latency
pup metrics query --query="avg:trace.servlet.request.duration{service:<name>} by {resource_name}" --from=1h

# 2. Find slow traces (>5 seconds — note nanoseconds!)
pup traces search --query="service:<name> AND @duration:>5000000000" --from=1h

# 3. Check resource utilization
pup metrics query --query="avg:system.cpu.user{service:<name>} by {host}" --from=1h

Service Health Overview

pup idp assist <service-name>       # Full context: owner, on-call, health, deps
pup slos list                       # Check SLO compliance
pup monitors list --tags="team:<team>"
pup incidents list --query="status:active"

Global Flags

Environment Variables

Advanced Usage

For detailed documentation beyond this quick reference, see:

• references/commands-reference.md — Full command reference across all 49 command groups
• references/workflows.md — Operational workflows: incident response, security audit, infrastructure review, runbooks
• references/query-syntax.md — Complete query syntax for logs, metrics, traces, RUM, and monitors
• references/advanced-features.md — Runbooks, ACP server, Live Debugger, IDP, fleet management, workflows, cost management

Runbooks (Local Execution Engine)

YAML-defined multi-step operational procedures stored in ~/.config/pup/runbooks/:

pup runbooks list                                              # List available runbooks
pup runbooks describe incident-triage                          # Inspect steps
pup runbooks run deploy-service --arg SERVICE=payments --arg VERSION=1.2.3
pup runbooks run deploy-service --dry-run                      # Preview without executing

ACP Server (Datadog AI Agent Integration)

Turns pup into a local AI agent server for Bits AI:

pup acp serve                        # Start server (auto-discovers Bits AI agent)
pup acp serve --agent-id <uuid>      # Target specific agent

Exposes ACP and OpenAI-compatible endpoints at http://127.0.0.1:9099.