pup

README

🐕 Give Your Agent a Puppy: Introducing Pup CLI

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!

Every AI agent needs a loyal companion. Meet Pup — the CLI that gives your agents full access to Datadog's observability platform (because even autonomous agents need good tooling, not just tricks).

What is Pup?

A comprehensive, AI-agent-ready CLI with 200+ commands across 33 Datadog products. We've unleashed the full power of Datadog's APIs so your agents can fetch metrics, sniff out errors, and track down issues without barking up the wrong API tree.

AI agents are the fastest-growing interface for infrastructure management. Companies like Vercel and AWS are racing to make their platforms agent-accessible, but we're leading the pack. Pup makes Datadog the alpha choice for AI-native workflows with 100% documented API coverage while competitors are still learning basic commands.

Why Your Agent Will Love It

• 🐾 Well-trained: Self-discoverable commands (no need to chase documentation)
• 🦮 Obedient: Structured JSON/YAML output for easy parsing
• 🐕🦺 On a leash: OAuth2 + PKCE for scoped access (no more long-lived keys running wild)
• 🐶 Knows all the tricks: Monitors, logs, metrics, RUM, security and more!

Try It (Humans Welcome Too!)

# Give your agent credentials (house-training, basically)
pup auth login

# Now they can fetch data like a good pup
pup monitors list --tags="team:api-platform"         # Fetch monitors
pup logs search --query="status:error" --from="1h"   # Sniff out errors
pup metrics query --query="avg:system.cpu.user{*}"   # Track the metrics tail

🐶 TL;DR: We built a comprehensive CLI so AI agents can use Datadog like a pro. Give your agent a pup. They're housetrained, loyal, and know way more tricks than you'd expect.

P.S. No actual puppies were harmed in the making of this CLI. Just a lot of Go code and API endpoints.

API Coverage

Pup implements 39 of 85+ available Datadog APIs (45.9% coverage).

See docs/COMMANDS.md for detailed command reference.

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

---

📊 Core Observability (6/9 implemented)

API Domain	Status	Pup Commands	Notes
Metrics	✅	metrics search, metrics query, metrics list, metrics get	V1 and V2 APIs supported
Logs	✅	logs search, logs list, logs aggregate	V1 and V2 APIs supported
Events	✅	events list, events search, events get	Infrastructure event management
RUM	✅	rum apps, rum sessions, rum metrics list/get, rum retention-filters list/get	Apps, sessions, metrics, retention filters (create/update pending)
APM Services	✅	apm services, apm entities, apm dependencies, apm flow-map	Services stats, operations, resources; entity queries; dependencies; flow visualization
Traces	❌	-	Not yet implemented
Profiling	❌	-	Not yet implemented
Session Replay	❌	-	Not yet implemented
Spans Metrics	❌	-	Not yet implemented

🔔 Monitoring & Alerting (6/9 implemented)

API Domain	Status	Pup Commands	Notes
Monitors	✅	monitors list, monitors get, monitors delete, monitors search	Full CRUD support with advanced search
Dashboards	✅	dashboards list, dashboards get, dashboards delete, dashboards url	Full management capabilities
SLOs	✅	slos list, slos get, slos create, slos update, slos delete, slos corrections	Full CRUD plus corrections
Synthetics	✅	synthetics tests list, synthetics locations list	Test management support
Downtimes	✅	downtime list, downtime get, downtime cancel	Full downtime management
Notebooks	✅	notebooks list, notebooks get, notebooks delete	Investigation notebooks supported
Dashboard Lists	❌	-	Not yet implemented
Powerpacks	❌	-	Not yet implemented
Workflow Automation	❌	-	Not yet implemented

🔒 Security & Compliance (6/9 implemented)

API Domain	Status	Pup Commands	Notes
Security Monitoring	✅	security rules list, security signals search, security findings search	Rules, signals, findings with advanced search
Static Analysis	✅	static-analysis ast, static-analysis custom-rulesets, static-analysis sca, static-analysis coverage	Code security analysis
Audit Logs	✅	audit-logs list, audit-logs search	Full audit log search and listing
Data Governance	✅	data-governance scanner-rules list	Sensitive data scanner rules
Application Security	❌	-	Not yet implemented
CSM Threats	❌	-	Not yet implemented
Cloud Security (CSPM)	❌	-	Not yet implemented
Sensitive Data Scanner	❌	-	Not yet implemented

☁️ Infrastructure & Cloud (6/8 implemented)

API Domain	Status	Pup Commands	Notes
Infrastructure	✅	infrastructure hosts list, infrastructure hosts get	Host inventory management
Tags	✅	tags list, tags get, tags add, tags update, tags delete	Host tag operations
Network	⏳	network flows list, network devices list	Placeholder - API endpoints pending
Cloud (AWS)	✅	cloud aws list	AWS integration management
Cloud (GCP)	✅	cloud gcp list	GCP integration management
Cloud (Azure)	✅	cloud azure list	Azure integration management
Containers	❌	-	Not yet implemented
Processes	❌	-	Not yet implemented

🚨 Incident & Operations (7/8 implemented)

API Domain	Status	Pup Commands	Notes
Incidents	✅	incidents list, incidents get, incidents attachments	Incident management with attachment support
On-Call (Teams)	✅	on-call teams (CRUD, memberships with roles)	Full team management system with admin/member roles
Case Management	✅	cases (create, search, assign, archive, projects)	Complete case management with priorities P1-P5
Error Tracking	✅	error-tracking issues search, error-tracking issues get	Error issue search and details
Service Catalog	✅	service-catalog list, service-catalog get	Service registry management
Scorecards	✅	scorecards list, scorecards get	Service quality scores
Fleet Automation	✅	fleet agents, fleet deployments, fleet schedules	Agent management, deployments, schedules (Preview)
Incident Services/Teams	❌	-	Not yet implemented

🔧 CI/CD & Development (1/3 implemented)

API Domain	Status	Pup Commands	Notes
CI Visibility	✅	cicd pipelines list, cicd events list	CI/CD pipeline visibility and events
Test Optimization	❌	-	Not yet implemented
DORA Metrics	❌	-	Not yet implemented

👥 Organization & Access (5/6 implemented)

API Domain	Status	Pup Commands	Notes
Users	✅	users list, users get, users roles	User and role management
Organizations	✅	organizations get, organizations list	Organization settings management
API Keys	✅	api-keys list, api-keys get, api-keys create, api-keys delete	Full API key CRUD
App Keys	✅	app-keys list, app-keys get, app-keys register, app-keys unregister	App key registration for Action Connections
Service Accounts	✅	-	Managed via users commands
Roles	❌	-	Only list via users

⚙️ Platform & Configuration (7/9 implemented)

API Domain	Status	Pup Commands	Notes
Usage Metering	✅	usage summary, usage hourly	Usage and billing metrics
Cost Management	✅	cost projected, cost attribution, cost by-org	Cost attribution by tags and organizations
Product Analytics	✅	product-analytics events send	Server-side product analytics events
Integrations	✅	integrations slack, integrations pagerduty, integrations webhooks	Third-party integrations support
Observability Pipelines	⏳	obs-pipelines list, obs-pipelines get	Placeholder - API endpoints pending
Miscellaneous	✅	misc ip-ranges, misc status	IP ranges and status
Key Management	❌	-	Not yet implemented
IP Allowlist	❌	-	Not yet implemented

Installation

Homebrew (macOS/Linux) - Coming soon!

brew tap datadog-labs/pack
brew install datadog-labs/pack/pup

Go Install

go install github.com/datadog-labs/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

Bearer Token Authentication (WASM / Headless)

For WASM builds or environments without keychain access, use a pre-obtained bearer token:

export DD_ACCESS_TOKEN="your-oauth-access-token"
export DD_SITE="datadoghq.com"

pup monitors list

API key authentication (DD_API_KEY + DD_APP_KEY) also works in WASM. See the WASM section below.

Authentication Priority

Pup checks for authentication in this order:

1. DD_ACCESS_TOKEN - Stateless bearer token (highest priority)
2. OAuth2 tokens (from pup auth login) - Used if valid tokens exist
3. 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_ACCESS_TOKEN: Bearer token for stateless auth (highest priority)
• DD_API_KEY: Datadog API key (optional if using OAuth2 or DD_ACCESS_TOKEN)
• DD_APP_KEY: Datadog Application key (optional if using OAuth2 or DD_ACCESS_TOKEN)
• 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)

Agent Mode

When pup is invoked by an AI coding agent, it automatically switches to agent mode which returns structured JSON responses optimized for machine consumption (including metadata, error details, and hints). Agent mode also auto-approves confirmation prompts.

Agent mode is auto-detected when any of these environment variables are set to 1 or true:

Variable	Agent
CLAUDE_CODE or CLAUDECODE	Claude Code
CURSOR_AGENT	Cursor
CODEX or OPENAI_CODEX	OpenAI Codex
AIDER	Aider
CLINE	Cline
WINDSURF_AGENT	Windsurf
GITHUB_COPILOT	GitHub Copilot
AMAZON_Q or AWS_Q_DEVELOPER	Amazon Q
GEMINI_CODE_ASSIST	Gemini Code Assist
SRC_CODY	Sourcegraph Cody
FORCE_AGENT_MODE	Any agent (manual override)

You can also enable it explicitly with the --agent flag or by setting FORCE_AGENT_MODE=1:

# Auto-detected (e.g., running inside Claude Code)
pup monitors list

# Explicit flag
pup monitors list --agent

# Environment variable override
FORCE_AGENT_MODE=1 pup monitors list

If you are integrating pup into an AI agent workflow, make sure the appropriate environment variable is set so responses are optimized for your agent. Without it, pup defaults to human-friendly output.

WASM

Pup compiles to WebAssembly (GOOS=js GOARCH=wasm) for use in browser-like runtimes such as Deno, Bun, and Cloudflare Workers.

Building

GOOS=js GOARCH=wasm go build -o pup.wasm .

# Copy the Go WASM support file
cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" .

Authentication

The WASM build supports stateless authentication — keychain storage and browser-based OAuth login are not available. Use either DD_ACCESS_TOKEN or API keys:

# Option 1: Bearer token
DD_ACCESS_TOKEN="your-token" DD_SITE="datadoghq.com" deno run pup.wasm monitors list

# Option 2: API keys
DD_API_KEY="your-api-key" DD_APP_KEY="your-app-key" deno run pup.wasm monitors list

The pup auth status command works in WASM and reports which credentials are configured. The login, logout, and refresh subcommands return guidance to use DD_ACCESS_TOKEN.

Limitations

• No local token storage (keychain/file) — use DD_ACCESS_TOKEN or API keys
• No browser-based OAuth login flow
• Networking relies on the host runtime's Fetch API

Running with Deno

import "./wasm_exec.js";

const go = new Go();
const wasm = await Deno.readFile("pup.wasm");
const result = await WebAssembly.instantiate(wasm, go.importObject);
go.run(result.instance);

Pre-built WASM archives (including wasm_exec.js) are available in GitHub Releases.

Development

# Run tests
go test ./...

# Build
go build -o pup .

# Build WASM
GOOS=js GOARCH=wasm go build -o pup.wasm .

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