EXAMPLES.md

Usage Examples

Common workflows and usage patterns for Pup CLI.

Authentication

OAuth2 Login (Recommended)

# Login with default site (datadoghq.com)
pup auth login

# Login with specific site
pup --site=datadoghq.eu auth login

# Check authentication status
pup auth status

# Logout
pup auth logout

API Key Authentication (Legacy)

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

Metrics

List Metrics

# List all metrics
pup metrics list

# Filter by pattern
pup metrics list --filter="system.*"
pup metrics list --filter="custom.app.*"

Search Metrics (v1 API)

# Classic query syntax
pup metrics search --query="avg:system.cpu.user{*}" --from="1h"

# Search with aggregation and grouping
pup metrics search --query="sum:app.requests{env:prod} by {service}" --from="4h"

Query Metrics (v2 API)

# Timeseries formula query
pup metrics query --query="avg:system.cpu.user{*}" --from="1h" --to="now"

# Query with aggregation
pup metrics query --query="sum:app.requests{env:prod} by {service}" --from="4h"

Monitors

List Monitors

# List all monitors
pup monitors list

# Filter by tag
pup monitors list --tag="env:production"
pup monitors list --tag="team:backend"

# Multiple tags
pup monitors list --tag="env:prod" --tag="service:api"

Get Monitor Details

# Get specific monitor by ID
pup monitors get 12345678

Delete Monitor

# Delete monitor (prompts for confirmation)
pup monitors delete 12345678

# Skip confirmation
pup monitors delete 12345678 --yes

Logs

Search Logs

# Search for errors in last hour
pup logs search --query="status:error" --from="1h" --to="now"

# Search by service
pup logs search --query="service:web-app status:warn" --from="30m"

# Complex query with attributes
pup logs search --query="@user.id:12345 status:error" --limit=100

# Search with time range
pup logs search \
  --query="service:api" \
  --from="2024-02-04T10:00:00Z" \
  --to="2024-02-04T11:00:00Z"

Aggregate Logs

# Count logs by status
pup logs aggregate \
  --query="service:web-app" \
  --from="1h" \
  --compute="count" \
  --group-by="status"

# Average duration by service
pup logs aggregate \
  --query="service:web-app" \
  --from="1h" \
  --compute="avg(@duration)" \
  --group-by="service"

# 99th percentile latency by service
pup logs aggregate \
  --query="env:prod" \
  --from="30m" \
  --compute="percentile(@duration, 99)" \
  --group-by="service"

# Multiple metrics in one query (comma-separated)
pup logs aggregate \
  --query="service:web-app" \
  --from="1h" \
  --compute="count,avg(@duration),percentile(@duration, 95)" \
  --group-by="service,status"

Search Logs in Specific Storage Tier

# Search Flex logs (cost-optimized storage tier)
pup logs search --query="service:api" --from="7d" --storage="flex"

# Search online archives (long-term storage)
pup logs search --query="status:error" --from="30d" --storage="online-archives"

# Search standard indexes (default, fastest tier)
pup logs search --query="service:web-app" --from="1h" --storage="indexes"

# Use Datadog's default storage behavior
pup logs search --query="status:warn" --from="1h"

Dashboards

List Dashboards

# List all dashboards
pup dashboards list

# Output as table
pup dashboards list --output=table

Get Dashboard

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

# Get public URL for sharing
pup dashboards url "abc-123-def"

Delete Dashboard

pup dashboards delete "abc-123-def" --yes

SLOs

List SLOs

# List all SLOs
pup slos list

# Filter by tag
pup slos list --tag="service:api"

Get SLO

pup slos get "abc-123-def"

Create SLO

pup slos create \
  --name="API Availability" \
  --type="metric" \
  --target=99.9 \
  --timeframe="30d"

Manage SLO Corrections

# List corrections for SLO
pup slos corrections list "abc-123-def"

# Create correction
pup slos corrections create "abc-123-def" \
  --start="2024-02-04T10:00:00Z" \
  --end="2024-02-04T11:00:00Z" \
  --category="deployment"

Incidents

List Incidents

# List all incidents
pup incidents list

# Filter by status
pup incidents list --status="active"

Get Incident

pup incidents get "abc-123"

Create Incident

pup incidents create \
  --title="High Error Rate in API" \
  --severity="SEV-2" \
  --customer-impacted=true

Update Incident

pup incidents update "abc-123" --status="resolved"

RUM (Real User Monitoring)

List RUM Applications

pup rum apps list

Get RUM Application

pup rum apps get "abc-123"

Search RUM Sessions

pup rum sessions search \
  --query="@application.id:abc-123" \
  --from="1h"

Security

List Security Rules

pup security rules list

Get Security Rule

pup security rules get "abc-123"

List Security Signals

pup security signals list --from="1h"

Search Security Findings

pup security findings search \
  --query="@severity:high"

APM Troubleshooting

List Instrumentation Errors for a Host

# Show APM instrumentation errors for a specific host
pup apm troubleshooting list --hostname my-host

# Narrow results to a specific time window
pup apm troubleshooting list --hostname my-host --timeframe 4h

Containers

List Containers

# List all containers
pup containers list

# Filter by tags
pup containers list --filter-tags="env:production"

# Group by image
pup containers list --group-by="image_name"

List Container Images

# List all container images
pup containers images list

# Filter images by tags
pup containers images list --filter-tags="env:production"

Infrastructure

List Hosts

# List all hosts
pup infrastructure hosts list

# Filter by tag
pup infrastructure hosts list --filter="env:production"

Fleet

List Fleet Agents

# Filter agents by hostname
pup fleet agents list --filter "hostname:my-host"

# Filter by IP address
pup fleet agents list --filter "ip_address:1.2.3.4"

# Boolean filter expression
pup fleet agents list --filter "(hostname:host-a OR hostname:host-b) AND env:prod"

Get Host

pup infrastructure hosts get "host-name"

Tags

List Host Tags

# List all host tags
pup tags list

Get Tags for Host

pup tags get "host-name"

Add Tags to Host

pup tags add "host-name" \
  --tag="env:production" \
  --tag="team:backend"

Update Host Tags

pup tags update "host-name" \
  --tag="env:prod" \
  --tag="service:api"

Users & Organizations

List Users

pup users list

Get User

pup users get "user-id"

List Roles

pup users roles list

Get Organization

pup organizations get

API Keys

List API Keys

pup api-keys list

Get API Key

pup api-keys get "key-id"

Create API Key

pup api-keys create --name="CI/CD Key"

Delete API Key

pup api-keys delete "key-id" --yes

Synthetics

List Synthetic Tests

pup synthetics tests list

Get Synthetic Test

pup synthetics tests get "test-id"

List Synthetic Locations

pup synthetics locations list

Workflows

Get a Workflow

pup workflows get <workflow-id>

Create a Workflow

pup workflows create --file=workflow.json

Update a Workflow

pup workflows update <workflow-id> --file=workflow.json

Delete a Workflow

pup workflows delete <workflow-id>

Execute a Workflow

# Run with inline payload (requires DD_API_KEY + DD_APP_KEY)
pup workflows run <workflow-id> --payload '{"key": "value"}'

# Run with payload from file
pup workflows run <workflow-id> --payload-file=params.json

# Run and wait for completion (default timeout: 5m)
pup workflows run <workflow-id> --wait

# Run with custom timeout
pup workflows run <workflow-id> --wait --timeout 2m

Manage Workflow Instances

# List recent executions
pup workflows instances list <workflow-id>

# List with pagination
pup workflows instances list <workflow-id> --limit=20 --page=2

# Get instance details
pup workflows instances get <workflow-id> <instance-id>

# Cancel a running instance
pup workflows instances cancel <workflow-id> <instance-id>

Runbooks

Runbooks are YAML files stored in ~/.config/pup/runbooks/ that encode multi-step operational procedures. Each step runs a pup command, shell command, HTTP request, Datadog Workflow, or an interactive confirmation.

List Available Runbooks

pup runbooks list
pup runbooks list --tag=type:deployment

Inspect a Runbook

pup runbooks describe deploy-service

Run a Runbook

# Run with required variables via --arg flags
pup runbooks run deploy-service --arg SERVICE=payments --arg VERSION=1.2.3

# Dry-run (print steps without executing)
pup runbooks run incident-triage --dry-run

Import a Runbook

# Copy a runbook YAML into ~/.config/pup/runbooks/
pup runbooks import ./my-runbook.yaml

Validate a Runbook

pup runbooks validate ./my-runbook.yaml

Example Runbook (YAML)

name: restart-service
description: Safely restart a service after checking monitors
vars:
  SERVICE:
    description: Service name
    required: true

steps:
  - name: Check active monitors
    kind: pup
    run: monitors list --tags="service:{{SERVICE}}"
    capture: MONITORS_JSON

  - name: Confirm restart
    kind: confirm
    message: "Restart {{SERVICE}}? Review monitors above."

  - name: Trigger restart workflow
    kind: datadog-workflow
    workflow_id: "abc-123"
    inputs:
      service: "{{SERVICE}}"
    on_failure: fail

  - name: Notify via webhook
    kind: http
    url: https://hooks.example.com/notify
    method: POST
    body: '{"text": "Restarted {{SERVICE}}"}'
    content_type: application/json
    on_failure: warn

Reusable Step Templates

Store shared step logic in ~/.config/pup/runbooks/_templates/<name>.yaml:

# _templates/slack-notify.yaml
kind: http
url: "{{SLACK_WEBHOOK}}"
method: POST
body: '{"text": "{{MESSAGE}}"}'
content_type: application/json
on_failure: warn

Reference a template in any runbook step:

steps:
  - name: Notify Slack
    template: slack-notify
    # Override any template field as needed

See docs/examples/runbooks/ for complete examples.

IDP (Service Catalog)

Get Full Service Context

# Get owner, on-call, health, dependencies, and metadata gaps in one call
pup idp assist my-service

# Useful as a starting point for incident response or code review
pup idp assist payments-api

Find Entities

# Search services by name (fuzzy match)
pup idp find payments

# Use kind: prefix to search other entity types
pup idp find "kind:team AND name:backend"

Get Ownership and On-Call

# Show owning team and current on-call responders
pup idp owner my-service

Show Service Dependencies

# List upstream (callers) and downstream (callees) services
pup idp deps my-service

Register a Service Definition

# POST a service.datadog.yaml to the Service Definitions API
pup idp register service.datadog.yaml

# Verify after registration
pup idp assist my-service

Incident Response Workflow with IDP

# Get full service context immediately
pup idp assist payments-api

# Investigate alerts for the service
pup monitors list --tag="service:payments-api"

# Check who is on-call
pup idp owner payments-api

# Review upstream services that may be affected
pup idp deps payments-api

Output Formatting

JSON Output (Default)

pup monitors list --output=json

YAML Output

pup monitors list --output=yaml

Table Output

pup monitors list --output=table

Custom Fields

pup monitors list --fields="id,name,type,status"

Advanced Usage

Custom Config File

pup --config=/path/to/config.yaml monitors list

Specify Datadog Site

pup --site=datadoghq.eu monitors list

Verbose Output (Debug)

pup --verbose monitors list

Skip Confirmation Prompts

pup --yes monitors delete 12345678

Read-Only Mode

# Block all write operations (create, update, delete)
pup --read-only monitors list
pup --read-only dashboards list

# Also available via env var or config file
DD_READ_ONLY=true pup monitors list

Common Workflows

Monitoring Dashboard

# List monitors for a service
pup monitors list --tag="service:api" --output=table

# Check recent logs
pup logs search --query="service:api" --from="1h" --output=table

# Query metrics
pup metrics query --query="avg:api.latency{*}" --from="1h"

Incident Response

# Create incident
pup incidents create --title="API Down" --severity="SEV-1"

# Search related logs
pup logs search --query="status:error service:api" --from="1h"

# Check monitors
pup monitors list --tag="service:api"

# Update incident status
pup incidents update "incident-id" --status="investigating"

Security Audit

# List recent security signals
pup security signals list --from="24h"

# Check security rules
pup security rules list

# Search security findings
pup security findings search --query="@severity:critical"

# Review audit logs
pup audit-logs list --from="7d"

Infrastructure Review

# List all hosts
pup infrastructure hosts list --output=table

# Get host details
pup infrastructure hosts get "host-name"

# Review host tags
pup tags list --output=table

Time Range Formats

Relative Times

--from="1h"    # 1 hour ago
--from="30m"   # 30 minutes ago
--from="7d"    # 7 days ago
--from="now"   # Current time

Absolute Times

--from="2024-02-04T10:00:00Z"
--to="2024-02-04T11:00:00Z"

Unix Timestamps

--from="1707048000"  # Unix timestamp in seconds

Environment Variables

# Authentication
export DD_API_KEY="your-api-key"
export DD_APP_KEY="your-app-key"
export DD_SITE="datadoghq.com"

# Configuration
export PUP_CONFIG="/path/to/config.yaml"
export PUP_OUTPUT="json"
export PUP_LOG_LEVEL="debug"

ACP Server (AI Agent Integration)

pup acp serve starts a local HTTP server that lets AI coding assistants and agents talk directly to Datadog Bits AI. It speaks two protocols:

• ACP (Agent Communication Protocol) — for ACP-native clients
• OpenAI-compatible — for tools like opencode, Cursor, or any @ai-sdk/openai-compatible client

Quick Start

# Authenticate first (notebooks_read + notebooks_write scopes required)
pup auth login

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

# Specify a particular agent
pup acp serve --agent-id <uuid>

# Custom port or bind address
pup acp serve --port 8080
pup acp serve --host 0.0.0.0 --port 9099

Endpoints

Method	Path	Protocol	Description
GET	/agent.json	ACP	Agent card / capability discovery
POST	/runs	ACP	Synchronous run — returns full response
POST	/runs/stream	ACP	Streaming run — SSE events
GET	/models or /v1/models	OpenAI	Model list
POST	/chat/completions or /v1/chat/completions	OpenAI	Chat completions (streaming or sync)

Testing with curl

# ACP sync
curl -s -X POST http://127.0.0.1:9099/runs \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": [{"type": "text", "text": "list my monitors with status alert"}]}]}' \
  | jq .output[0].content[0].text

# ACP streaming
curl -X POST http://127.0.0.1:9099/runs/stream \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": [{"type": "text", "text": "what services have errors in the last hour?"}]}]}'

# OpenAI-compatible
curl -s -X POST http://127.0.0.1:9099/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "datadog-ai", "messages": [{"role": "user", "content": "how many monitors are currently alerting?"}]}' \
  | jq .choices[0].message.content

opencode Setup

Add to ~/Library/Application Support/opencode/opencode.jsonc (macOS) or ~/.config/opencode/opencode.jsonc (Linux):

{
  "$schema": "https://opencode.ai/config.json",
  "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"
      }
    }
  }
}

Then start the server (pup acp serve) and select the Datadog AI provider in opencode.

Configuration File

Create ~/.config/pup/config.yaml:

site: datadoghq.com
output: json
verbose: false

# Default time ranges
default_from: 1h
default_to: now

# Output preferences
output_format: json
table_max_width: 120