pup

[PREVIEW] Pup - Datadog API CLI Wrapper

NOTICE: This is in Preview mode, we are fine tuning the interactions and bugs that arise. Please file issues or submit PRs. Thank you for your early interest!

A Go-based command-line wrapper for easy interaction with Datadog APIs.

Features

• Native Go Implementation: Fast, cross-platform binary
• OAuth2 Authentication: Secure browser-based login with PKCE protection
• API Key Support: Traditional API key authentication still available
• Simple Commands: Intuitive CLI for common Datadog operations
• JSON Output: Structured output for easy parsing and automation
• Dynamic Client Registration: Each installation gets unique OAuth credentials

API Coverage

Pup implements 38 of 85+ available Datadog APIs (44.7% coverage).

Summary:

• ✅ 35 Working - Fully implemented and functional
• ⏳ 3 Planned - Skeleton implementation, endpoints pending
• ❌ 48+ Not Implemented - Available in Datadog but not yet in pup

See docs/COMMANDS.md for detailed command reference.

💡 Tip: Use Ctrl/Cmd+F to search for specific APIs. Request features via GitHub Issues.

Installation

Homebrew (macOS/Linux)

brew tap datadog/pack
brew install datadog/pack/pup

Go Install

go install github.com/DataDog/pup@latest

Manual Download

Download pre-built binaries from the latest release.

Authentication

Pup supports two authentication methods. OAuth2 is preferred and will be used automatically if you've logged in.

OAuth2 Authentication (Preferred)

OAuth2 provides secure, browser-based authentication with automatic token refresh.

# Set your Datadog site (optional)
export DD_SITE="datadoghq.com"  # Defaults to datadoghq.com

# Login via browser
pup auth login

# Use any command - OAuth tokens are used automatically
pup monitors list

# Check status
pup auth status

# Logout
pup auth logout

Token Storage: Tokens are stored securely in your system's keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). Set DD_TOKEN_STORAGE=file to use file-based storage instead.

Note: OAuth2 requires Dynamic Client Registration (DCR) to be enabled on your Datadog site. If DCR is not available yet, use API key authentication.

See docs/OAUTH2.md for detailed OAuth2 documentation.

API Key Authentication (Fallback)

If OAuth2 tokens are not available, Pup automatically falls back to API key authentication.

export DD_API_KEY="your-datadog-api-key"
export DD_APP_KEY="your-datadog-application-key"
export DD_SITE="datadoghq.com"  # Optional, defaults to datadoghq.com

# Use any command - API keys are used automatically
pup monitors list

Authentication Priority

Pup checks for authentication in this order:

1. OAuth2 tokens (from pup auth login) - Used if valid tokens exist
2. API keys (from DD_API_KEY and DD_APP_KEY) - Used if OAuth tokens not available

Usage

Authentication

# OAuth2 login (recommended)
pup auth login

# Check authentication status
pup auth status

# Refresh access token
pup auth refresh

# Logout
pup auth logout

Test Connection

pup test

Monitors

# List all monitors
pup monitors list

# Get specific monitor
pup monitors get 12345678

# Delete monitor
pup monitors delete 12345678 --yes

Metrics

# Search metrics using classic query syntax (v1 API)
pup metrics search --query="avg:system.cpu.user{*}" --from="1h"

# Query time-series data (v2 API)
pup metrics query --query="avg:system.cpu.user{*}" --from="1h"

# List available metrics
pup metrics list --filter="system.*"

Dashboards

# List all dashboards
pup dashboards list

# Get dashboard details
pup dashboards get abc-123-def

# Delete dashboard
pup dashboards delete abc-123-def --yes

SLOs

# List all SLOs
pup slos list

# Get SLO details
pup slos get abc-123

# Delete SLO
pup slos delete abc-123 --yes

Incidents

# List all incidents
pup incidents list

# Get incident details
pup incidents get abc-123-def

Global Flags

• -o, --output: Output format (json, table, yaml) - default: json
• -y, --yes: Skip confirmation prompts for destructive operations

Environment Variables

• DD_API_KEY: Datadog API key (optional if using OAuth2)
• DD_APP_KEY: Datadog Application key (optional if using OAuth2)
• DD_SITE: Datadog site (default: datadoghq.com)
• DD_AUTO_APPROVE: Auto-approve destructive operations (true/false)
• DD_TOKEN_STORAGE: Token storage backend (keychain or file, default: auto-detect)

Development

# Run tests
go test ./...

# Build
go build -o pup .

# Run without building
go run main.go monitors list

License

Apache License 2.0 - see LICENSE for details.

Documentation

For detailed documentation, see CLAUDE.md.