Stop Building Fragile AI Agents! Pup CLI Unleashes 320+ Datadog Commands

Your AI agent just hallucinated its way through another production incident. It claimed the API was "fine" while your monitors screamed red. You gave it a curl script and prayed. It returned JSON soup that no parser could untangle. Sound familiar?

Here's the brutal truth: most AI agents are only as good as their tools. And until now, connecting autonomous systems to real observability platforms meant duct-taping together brittle API calls, managing long-lived secrets like radioactive waste, and praying your agent didn't delete the wrong dashboard at 3 AM.

Enter Pup CLI — the secret weapon that top platform engineers at Datadog built to solve exactly this nightmare. Born from the datadog-labs/pup repository, this isn't another wrapper script. It's a comprehensive, AI-native command-line interface exposing 320+ commands across 33+ Datadog product domains, engineered from the ground up in Rust for speed, security, and machine consumption.

Think of it as giving your agent a highly trained service dog instead of a broken leash. Self-discoverable commands. Structured JSON output. OAuth2 with PKCE. Automatic agent mode detection. And yes — it compiles to WebAssembly for edge deployments.

Ready to stop babysitting your AI infrastructure tools? Let's dive into why Pup CLI is becoming the invisible backbone of serious agent-driven operations.

What Is Pup CLI? The Full Story Behind datadog-labs/pup

Pup CLI is Datadog's official open-source command-line companion designed specifically for AI agents — though humans are absolutely welcome too. Built in Rust for maximum performance and safety, it transforms Datadog's massive API surface into a navigable, self-documenting command structure that both humans and machines can consume without confusion.

The project emerged from a critical observation: AI agents are the fastest-growing interface for infrastructure management, yet most platforms still force them through human-centric web UIs or poorly documented REST endpoints. Companies like Vercel and AWS are racing to make their platforms agent-accessible, but Datadog's Labs team moved first — creating a tool that makes Datadog "a great choice for AI-native workflows by exposing the API surface in a way agents can navigate without barking up the wrong tree."

What makes Pup genuinely different? It's not just a CLI — it's an ecosystem. The repository ships with embedded AI skills for Claude, Cursor, Codex, OpenCode, and pi.dev. It includes a local ACP (Agent Communication Protocol) server that turns Pup into an OpenAI-compatible endpoint. It supports YAML-defined runbooks for operational procedures. And it auto-detects when it's running inside an AI coding environment, switching to structured JSON responses optimized for machine parsing.

The project carries an Apache 2.0 license, maintains active CI pipelines, and accepts feature requests through GitHub Issues. With its wasm32-wasip2 target support, Pup runs in WASI-compatible runtimes including Wasmtime, Wasmer, and Cloudflare Workers — making it deployable to edge environments where traditional binaries can't reach.

Key Features That Make Pup CLI Insanely Powerful

Self-Discoverable Command Structure

Pup eliminates the documentation scavenger hunt. Commands follow intuitive patterns: pup <domain> <action>. Your agent can explore via pup --help or consume machine-readable schemas through pup agent schema. No more guessing whether the endpoint is /api/v1/monitor or /api/v2/monitor.

Structured Output for Machine Parsing

Every command supports -o json, -o yaml, or -o table. In agent mode (auto-detected or forced with --agent), responses include metadata, error details, and hints — structured precisely for LLM consumption. Your agent gets clean data, not HTML soup.

Enterprise-Grade Security with OAuth2 + PKCE

No more long-lived API keys running wild. Pup's preferred authentication uses browser-based OAuth2 with PKCE, storing tokens in your system's native keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). Tokens refresh automatically. Scoped access means compromise is contained, not catastrophic.

Automatic Agent Mode Detection

Pup recognizes when it's invoked by Claude Code, Cursor, OpenAI Codex, Aider, Cline, Windsurf, GitHub Copilot, Amazon Q, Gemini Code Assist, Sourcegraph Cody, or pi.dev. Set the appropriate environment variable, and Pup switches to machine-optimized responses with auto-approved confirmations.

WebAssembly Compilation

Build for wasm32-wasip2 and deploy to Wasmtime, Wasmer, or Cloudflare Workers. Stateless authentication via DD_ACCESS_TOKEN makes edge deployment seamless. The same binary that runs on your laptop runs in a serverless edge function.

Embedded AI Skills and ACP Server

Install domain-specific skills directly into your coding assistant with pup skills install. Launch pup acp serve to create an OpenAI-compatible local server that proxies to Datadog Bits AI — any tool using @ai-sdk/openai-compatible can now query your observability data.

YAML Runbook Engine

Define multi-step operational procedures in YAML with variable interpolation, step templates, HTTP calls, shell execution, Datadog Workflow triggers, and conditional logic. Store in ~/.config/pup/runbooks/ and execute with pup runbooks run.

5 Real-World Scenarios Where Pup CLI Dominates

1. Autonomous Incident Response

Your PagerDuty webhook triggers an AI agent. The agent needs to assess scope fast — check monitors, query logs, inspect traces, and create an incident timeline. With Pup, it executes pup monitors list --tags="service:payments", pup logs search --query="service:payments status:error" --from="15m", and pup incidents create in sequence — all returning structured JSON it can reason about and present to on-call engineers.

2. Infrastructure-as-Code Validation Pipelines

Before Terraform applies, your CI agent validates that monitors exist, SLOs are configured, and dashboards reference real metrics. Pup commands in agent mode return deterministic JSON that gates deployments: pup slos list | jq '.data[] | select(.name=="api-availability")' becomes a reliable pre-flight check.

3. Security Compliance Automation

A scheduled agent audits cloud security posture across AWS, GCP, and Azure. It runs pup security findings analyze with DDSQL queries, exports results via pup audit-logs search, and generates compliance reports — all without human intervention or credential exposure beyond scoped OAuth tokens.

4. Cost Optimization Intelligence

Your FinOps agent monitors cloud spend attribution daily. It queries pup costs datadog attribution, pup costs ccm budgets, and pup usage hourly to detect anomalies, then triggers pup runbooks run cost-alert to notify teams via Slack integration. Structured output enables trend analysis and predictive alerting.

5. Edge-Native Observability in WASM

A Cloudflare Worker at the edge needs to check Datadog status before routing traffic. Compiled to WASM with cargo build --target wasm32-wasip2, Pup runs inside the worker with DD_ACCESS_TOKEN, executing pup misc status or pup service-catalog get to make routing decisions without round-tripping to a central service.

Step-by-Step Installation & Setup Guide

macOS and Linux via Homebrew (Recommended)

# Add the Datadog Labs tap
brew tap datadog-labs/pack

# Install Pup
brew install datadog-labs/pack/pup

# Verify installation
pup --version

Build from Source (All Platforms)

# Clone the repository
git clone https://github.com/DataDog/pup.git && cd pup

# Build optimized release binary
cargo build --release

# Install to system PATH
cp target/release/pup /usr/local/bin/pup

# Or run directly without installing
cargo run -- --help

Manual Binary Download

Download pre-built binaries for your platform from the latest GitHub release. Extract and place in your PATH.

WebAssembly Build (Advanced)

# Install the WASI target
rustup target add wasm32-wasip2

# Build WASM module
cargo build --target wasm32-wasip2 --no-default-features --features wasi --release

# Run with Wasmtime
wasmtime run --env DD_ACCESS_TOKEN="your-token" \
  target/wasm32-wasip2/release/pup.wasm -- monitors list

Authentication Setup

OAuth2 (Preferred — Secure and Automatic):

# Optional: set your Datadog site
export DD_SITE="datadoghq.com"  # Default; use datadoghq.eu for EU

# Browser-based login with automatic token storage
pup auth login

# Verify authentication
pup auth status

# Tokens auto-refresh; logout when done
pup auth logout

API Key Fallback (For CI/CD or Restricted Environments):

export DD_API_KEY="your-datadog-api-key"
export DD_APP_KEY="your-datadog-application-key"
export DD_SITE="datadoghq.com"

# Pup auto-detects these when OAuth tokens unavailable
pup monitors list

Bearer Token for WASM/Headless:

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

# Highest priority authentication method
pup metrics query --query="avg:system.cpu.user{*}" --from="1h"

Authentication Priority: Pup checks DD_ACCESS_TOKEN first, then OAuth2 tokens from pup auth login, then DD_API_KEY/DD_APP_KEY.

REAL Code Examples from the Repository

Example 1: OAuth2 Authentication and Monitor Management

The README provides this complete authentication and usage pattern. Let's break down exactly what happens:

# 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

What's happening here? The pup auth login command initiates a browser-based OAuth2 flow with PKCE — the same security standard used by mobile apps. Your browser opens, you authenticate with Datadog, and Pup receives a short-lived authorization code it exchanges for access and refresh tokens. These tokens store in your OS keychain, not plaintext files.

The subsequent commands demonstrate Pup's domain-action pattern. pup monitors list with --tags filtering shows how agents can scope queries to relevant resources. pup logs search uses Datadog's query syntax with time bounding — critical for preventing runaway log scans. pup metrics query demonstrates the V2 metrics API with classic query syntax support.

Example 2: Agent Mode Auto-Detection and Explicit Control

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

# Explicit flag for testing or non-standard environments
pup monitors list --agent

# Environment variable override for CI pipelines or custom agents
FORCE_AGENT_MODE=1 pup monitors list

The critical insight: Pup inspects environment variables to determine if a human or machine is calling. When CLAUDE_CODE=1, CURSOR_AGENT=1, or any recognized agent variable is set, output format changes dramatically — confirmations auto-approve, responses include structured metadata, and error messages carry machine-actionable hints.

This matters because LLMs parse text differently than humans. A human sees a pretty table; an LLM needs JSON with schema. Agent mode ensures your automation doesn't choke on formatting or hang on interactive prompts.

Example 3: WASM Execution with Stateless Authentication

# Option 1: Bearer token for stateless WASM execution
DD_ACCESS_TOKEN="your-token" DD_SITE="datadoghq.com" \
  wasmtime run target/wasm32-wasip2/release/pup.wasm -- monitors list

# Option 2: API keys in WASM environment
DD_API_KEY="your-api-key" DD_APP_KEY="your-app-key" \
  wasmtime run target/wasm32-wasip2/release/pup.wasm -- --help

Why WASM changes everything: Traditional CLIs assume filesystem access, persistent state, and interactive terminals. WASM strips these away. Pup's WASM build uses only environment variables for configuration — no keychain, no browser, no file-based token storage.

The -- separator after pup.wasm is crucial: it passes subsequent arguments to Pup itself, not to wasmtime. This pattern enables Pup to run in Cloudflare Workers, where each invocation is stateless and must complete within milliseconds. Your edge function checks Datadog status without maintaining infrastructure.

Example 4: YAML Runbook with Variable Interpolation

# List available runbooks from ~/.config/pup/runbooks/
pup runbooks list

# Inspect steps before execution
pup runbooks describe incident-triage

# Execute with variable substitution
pup runbooks run deploy-service --arg SERVICE=payments --arg VERSION=1.2.3

# Validate without executing
pup runbooks validate ./my-runbook.yaml

# Dry-run to preview execution
pup runbooks run deploy-service --dry-run

Runbooks are Pup's secret weapon for operational reliability. Unlike ad-hoc scripts, YAML runbooks enforce structure: each step has a type (pup, shell, http, datadog-workflow, confirm), failure handling (on_failure: fail|warn|ignore), conditional execution (when: on_success|on_failure|always), and output capture (capture: VAR_NAME for later steps).

Variable interpolation via {{VAR_NAME}} enables reuse across environments. Templates in _templates/ reduce duplication. Polling configuration handles long-running operations. This isn't scripting — it's operational programming with guardrails.

Example 5: AI Skills Installation for Claude Code

# Install all skills for auto-detected platform
pup skills install

# Target specific AI assistant
pup skills install claude
pup skills install cursor
pup skills install codex

# Install to project-local directory instead of global
pup skills install claude --project

# List available capabilities
pup skills list
pup skills list --type=skill
pup skills list --type=agent

Skills transform Pup from tool to teammate. When installed to ~/.claude/skills/, these domain-specific capabilities extend Claude Code's understanding of Datadog operations. Instead of generic "check the logs" requests, Claude can execute precise pup logs search with proper query syntax, interpret structured responses, and chain subsequent commands.

The --project flag keeps skills local to repositories — crucial for teams with different Datadog environments or compliance requirements. Skills install as native formats per platform (Claude's subagent format, Cursor's SKILL.md pattern), ensuring seamless integration.

Advanced Usage & Best Practices

Optimize Agent Workflows with Schema Discovery

Instead of hardcoding commands, have your agent call pup agent schema at startup to discover available commands dynamically. This future-proofs against API additions and enables self-healing when commands change.

Leverage Output Piping and JQ

# Extract specific monitor IDs for bulk operations
pup monitors list --tags="env:prod" -o json | \
  jq -r '.data[] | select(.options.evaluation_delay > 60) | .id' | \
  xargs -I {} pup monitors get {} -o json

Secure Token Rotation

Set DD_TOKEN_STORAGE=file only in containerized environments where keychain is unavailable. Prefer keychain storage for developer machines. Rotate DD_ACCESS_TOKEN via your secret manager for WASM deployments.

Runbook-Driven Incident Response

Encode your runbooks before incidents. The confirm step type ensures human approval for destructive actions, while datadog-workflow steps trigger automated remediation. Store runbooks in version control and validate in CI with pup runbooks validate.

ACP Server for Custom Tooling

# Start local OpenAI-compatible endpoint
pup acp serve --port 9099

Point internal tools at http://127.0.0.1:9099 to let non-Datadog-specific AI systems query observability data. The ACP server bridges Pup's command structure to any OpenAI-compatible client.

Comparison with Alternatives

The verdict: Raw APIs offer flexibility at massive integration cost. SDKs lock you into language ecosystems. The web UI excludes automation entirely. Pup occupies the unique intersection of agent-native design, comprehensive coverage, and operational reliability.

FAQ: Common Developer Concerns

Q: Is Pup CLI officially supported by Datadog? A: Pup originates from Datadog Labs — an official innovation arm. It carries Datadog's engineering standards (Rust, CI/CD, Apache 2.0) but moves faster than core product release cycles. Feature requests go through GitHub Issues.

Q: Can I use Pup in production CI/CD pipelines? A: Absolutely. Use API key authentication (DD_API_KEY + DD_APP_KEY) or DD_ACCESS_TOKEN for headless environments. The --yes flag auto-approves destructive operations. Set DD_AUTO_APPROVE=true for fully automated pipelines.

Q: How does Pup handle API rate limits? A: Pup respects Datadog's API rate limits and returns standard HTTP status codes. In agent mode, rate limit responses include structured retry guidance. Implement exponential backoff in your agent logic for resilient automation.

Q: What's the difference between Pup and Datadog's MCP server? A: Pup is a comprehensive CLI for direct command execution. The MCP server (referenced for Profiling) follows Anthropic's Model Context Protocol for IDE integration. They complement each other — Pup for scripting and automation, MCP for conversational IDE assistance.

Q: Can I extend Pup with custom commands? A: While Pup doesn't support plugin architecture yet, the runbook engine (pup runbooks) enables custom operational procedures. Shell and HTTP step types let you integrate arbitrary tools into structured workflows.

Q: Is WASM support production-ready? A: The WASM build is functional with known limitations: no keychain storage, no browser OAuth, and networking depends on host runtime. It's ideal for edge deployments with DD_ACCESS_TOKEN or API keys, not interactive use.

Q: How do I migrate from custom API scripts to Pup? A: Start by replacing your most frequent API calls — monitor queries, log searches, metric aggregation. Map your endpoints to pup <domain> <action> patterns. Use -o json to verify output structure matches your parsing logic, then swap incrementally.

Conclusion: Give Your Agent the Companion It Deserves

The era of fragile AI agents cobbled together with curl and hope is ending. Pup CLI represents a fundamental shift: observability tools built for machines, not merely tolerating them. With 320+ commands spanning 33+ Datadog products, OAuth2 security, automatic agent mode detection, WebAssembly deployment, and embedded AI skills, Pup transforms Datadog from a human-centric dashboard into a true agent-native platform.

Whether you're automating incident response, validating infrastructure pipelines, deploying edge-native observability, or simply tired of parsing undocumented JSON responses — Pup delivers the reliability and structure your autonomous systems demand.

The repository is actively maintained, open-source under Apache 2.0, and waiting for your contributions. Stop forcing your agents to bark up the wrong API tree.

👉 Give your agent a Pup today: github.com/DataDog/pup

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