pup

pup

Give your AI agent a Pup — a CLI companion with 200+ commands across 33 Datadog products.

Stars: 304

Visit
 screenshot

Pup is a CLI tool designed to give AI agents access to Datadog's observability platform. It offers over 200 commands across 33 Datadog products, allowing agents to fetch metrics, identify errors, and track issues efficiently. Pup ensures that AI agents have the necessary tooling to perform tasks seamlessly, making Datadog the preferred choice for AI-native workflows. With features like self-discoverable commands, structured JSON/YAML output, OAuth2 + PKCE for secure access, and comprehensive API coverage, Pup empowers AI agents to monitor, log, analyze metrics, and enhance security effortlessly.

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!

CI Go Version License

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 38 of 85+ available Datadog APIs (44.7% 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 (6/7 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
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.

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for pup

Similar Open Source Tools

For similar tasks

For similar jobs