DataDog/pup

:dog2: Give Your Agent a Puppy: Introducing Pup CLI

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 covering a wide range of Datadog product domains. 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 a great choice for AI-native workflows by exposing the API surface in a way agents can navigate without barking up the wrong tree.

Why Your Agent Will Love It

• :paw_prints: Well-trained: Self-discoverable commands (no need to chase documentation)
• :guide_dog: Obedient: Structured JSON/YAML output for easy parsing
• :service_dog: On a leash: OAuth2 + PKCE for scoped access (no more long-lived keys running wild)
• :dog: 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

:dog: 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 Rust code and API endpoints.

API Coverage

Pup covers most major Datadog product surfaces. See docs/COMMANDS.md for the canonical command reference, or run pup --help (or pup agent schema for machine-readable output) for the live list of commands as built.

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

Installation

Homebrew (macOS/Linux)

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

Build from Source

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

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, defaults to datadoghq.com).
# Common values: datadoghq.com, datadoghq.eu, us3.datadoghq.com,
# us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, ddog-gov.com.
# Other Datadog sites are also accepted.
export DD_SITE="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

Multiple sites and orgs

Pup persists each login as a separate session, so you can authenticate against multiple Datadog sites and orgs and switch between them with --org <name> (or DD_ORG=<name>) on any subcommand.

# Login to a non-default site. --site is only accepted by `pup auth login`
# and `pup auth status`. For other commands, select the site via DD_SITE
# (or use a named session and pass --org on every subsequent command; see
# the Named session examples below).
pup auth login --site datadoghq.eu
DD_SITE=datadoghq.eu pup monitors list

# Named session for a parent/child sub-org on the same site.
pup auth login --org staging-child
pup monitors list --org staging-child     # site recalled from the session, no DD_SITE needed

# Named session on another site. DD_SITE / --site is only needed at login.
pup auth login --site ap2.datadoghq.com --org ap2-prod
pup monitors list --org ap2-prod          # site recalled

# SAML/SSO org with a vanity login page (e.g. acme.datadoghq.com). Pass the
# full host via --site; it routes the consent page to the right tenant and is
# also used for subsequent API calls, not just the login/consent flow.
pup auth login --org acme-prod --site acme.datadoghq.com

# Pre-target a specific org by UUID (sent as dd_oid). Skips the org switcher
# when the browser session already matches and pre-routes SAML/SSO. The UUID
# is persisted and re-emitted on subsequent `pup auth login` invocations for
# the same named session.
pup auth login --org acme-prod --org-uuid 11111111-2222-3333-4444-555555555555

# List all stored sessions (site, org, org_uuid, scopes, expiry, status).
pup auth list

# Refresh or log out a specific named session.
pup auth refresh --org staging-child
pup auth logout --org staging-child       # clears only that named session

Note: pup auth logout (default session) also deletes the shared DCR client credentials for that site. Named-org sessions on the same site keep their access tokens but will fail to refresh until the shared credentials are re-registered, which happens automatically on the next pup auth login on that site (any org, named or default). Logging out a named session (--org <name>) does not touch the shared client credentials.

Site selection rules (when pup resolves a site for a non-auth command):

1. DD_SITE env var (or site: in ~/.config/pup/config.yaml), if set.
2. The site recorded in ~/.config/pup/sessions.json for the named --org / DD_ORG.
3. Default: datadoghq.com.

pup auth login and pup auth status additionally accept --site, which wins over the above for those two commands.

Each org name maps to exactly one session, so step 2 is always unambiguous. An unnamed (default) session can't be selected by --org at all -- it has no name to look up.

Token Storage: By default, OAuth tokens and DCR client credentials are stored in your platform's secure store: macOS Keychain (via Apple's Security framework), Linux Secret Service (via the keyring crate), or Windows Credential Manager (via the keyring crate; sharded across multiple WinCred entries to stay within WinCred's per-record size limit). When no secure store is available, pup falls back to JSON files under ~/.config/pup/ with 0600 permissions; in file mode tokens and client credentials are kept in separate files (tokens_<site>.json, client_<site>.json). In either mode, all tokens for a given site share one tokens entry, keyed internally by org name.

Within a single command, the per-site entry is read at most once (reads are memoized for the process), so the OS keychain prompts at most once per site even when a command touches credentials several times.

The storage backend can be overridden with DD_TOKEN_STORAGE (env var) or token_storage in the config file (env var takes precedence):

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 auth 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

# Print a live 1 week dashboard URL
pup dashboards url abc-123-def --from=now-1w --to=now --live=true

# 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)
• PUP_TRUST_SITE: Trust a non-Datadog --site/DD_SITE host for this invocation without a prompt (true/1). For durable trust, add the host to trusted_sites in the config file. See docs/TROUBLESHOOTING.md.
• DD_AUTO_APPROVE: Auto-approve destructive operations (true/false)
• DD_TOKEN_STORAGE: Token storage backend (keychain (default) or file). Can also be set as token_storage in the config file.

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:

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 via the wasm32-wasip2 target for use in WASI-compatible runtimes such as Wasmtime, Wasmer, and Cloudflare Workers.

Building

# Install the WASI target
rustup target add wasm32-wasip2

# Build for WASI
cargo build --target wasm32-wasip2 --no-default-features --features wasi --release

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" wasmtime run target/wasm32-wasip2/release/pup.wasm -- monitors list

# Option 2: API keys
DD_API_KEY="your-api-key" DD_APP_KEY="your-app-key" wasmtime run target/wasm32-wasip2/release/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
• Extensions are not included in WASM builds; pup extension ... and installed extension dispatch are native-only
• Networking relies on the host runtime's networking capabilities

Running with Wasmtime

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

# Or with API keys
wasmtime run --env DD_API_KEY="key" --env DD_APP_KEY="key" target/wasm32-wasip2/release/pup.wasm -- --help

Runbooks

pup runbooks is a local execution engine for YAML-defined operational procedures. Runbooks live in ~/.config/pup/runbooks/ and encode multi-step tasks — from deployment gates to incident triage — using pup, shell, HTTP, Datadog Workflow, and interactive confirmation steps.

# List available runbooks
pup runbooks list

# Inspect a runbook's steps
pup runbooks describe incident-triage

# Run a runbook, passing required variables
pup runbooks run deploy-service --arg SERVICE=payments --arg VERSION=1.2.3

# Dry-run (show steps without executing)
pup runbooks run deploy-service --dry-run

# Import a runbook from a file
pup runbooks import ./my-runbook.yaml

# Validate a runbook file without running it
pup runbooks validate ./my-runbook.yaml

Runbook Features

• Step types: pup (Datadog commands), shell, http, datadog-workflow, confirm
• Variable interpolation: {{VAR_NAME}} in any field, passed via --arg KEY=VALUE
• Reusable templates: Store shared step definitions in _templates/ and reference them with template: <name>
• HTTP steps: Full method support (GET/POST/PUT/PATCH/DELETE) with body, headers, content_type, and body_file
• Failure handling: on_failure: fail|warn|ignore and optional: true per step
• Conditional execution: when: on_success|on_failure|always
• Polling: poll.interval, poll.timeout, poll.until for long-running operations
• Output capture: capture: VAR_NAME stores stdout for use in later steps
• Timestamped output: Every step shows start time, elapsed duration, and labeled stdout/stderr

See docs/examples/runbooks/ for ready-to-use examples and docs/EXAMPLES.md for full reference.

Agent Skills

Pup ships a set of skills and domain agents embedded in the binary, installable to any AI coding assistant. Run pup skills list to see what's available in the version you have installed.

# Install all skills and agents for the auto-detected platform
pup skills install

# Install for a specific platform (positional arg)
pup skills install claude
pup skills install cursor
pup skills install codex
pup skills install opencode
pup skills install pi
pup skills install devin

# Install for every supported platform at once
pup skills install all

# By default installs go to the user-global directory; --project keeps them local
pup skills install claude --project

# List available skills and agents
pup skills list
pup skills list --type=skill
pup skills list --type=agent

# Install a specific skill by name
pup skills install claude --name dd-monitors

For Claude Code, skills install to ~/.claude/skills/ (or .claude/skills/ with --project) and agents install to ~/.claude/agents/ (native subagent format). If the CLAUDE_CONFIG_DIR environment variable is set, user-scope installs go to $CLAUDE_CONFIG_DIR/skills/ and $CLAUDE_CONFIG_DIR/agents/ instead of ~/.claude/. For Cursor, Codex, opencode, and Devin, everything installs as SKILL.md under that tool's skills directory (e.g. ~/.cursor/skills/, ~/.codex/skills/, ~/.config/opencode/skills/, and Devin's ~/.agents/skills/ — or .agents/skills/ with --project).

Pup ships plugin manifest files for several AI coding assistants:

# Claude Code
/plugin marketplace add DataDog/pup

# Codex (reads .codex-plugin/plugin.json from the repo, or marketplace.json from ~/.agents/plugins/)

# Cursor (reads .cursor-plugin/plugin.json from the repo)

ACP Server

pup acp serve turns pup into a local AI agent server, letting coding tools talk directly to Datadog Bits AI. It supports two protocols:

• ACP — Agent Communication Protocol for ACP-native clients
• OpenAI-compatible — POST /chat/completions for opencode, Cursor, and any @ai-sdk/openai-compatible client

# Start the server (auto-discovers your first Datadog AI agent)
pup acp serve

# Or target a specific agent
pup acp serve --agent-id <uuid> --port 9099

Point any OpenAI-compatible client at http://127.0.0.1:9099 to start asking questions about your Datadog environment.

opencode (~/Library/Application Support/opencode/opencode.jsonc):

{
  "provider": {
    "datadog": {
      "name": "Datadog AI",
      "npm": "@ai-sdk/openai-compatible",
      "models": { "datadog-ai": { "name": "Datadog AI Agent" } },
      "options": { "baseURL": "http://127.0.0.1:9099" }
    }
  }
}

See docs/EXAMPLES.md#acp-server for full usage details.

Development

# Run tests
cargo test

# Build
cargo build --release

# Lint
cargo clippy -- -D warnings

# Format check
cargo fmt --check

# Build WASM
rustup target add wasm32-wasip2
cargo build --target wasm32-wasip2 --no-default-features --features wasi

# Run without building
cargo run -- monitors list

License

Apache License 2.0 - see LICENSE for details.

Documentation

For detailed documentation, see CLAUDE.md.