- Installs
- 7.6K
- Last 24h
- +68
- Trending rank
- #2719
- Security
- Warn
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/datadog-labs/agent-skills --skill dd-pup- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads dd-pup automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
pup (Datadog CLI)
Pup CLI for Datadog API operations. Supports OAuth2 and API key auth.
Quick Reference
| Task | Command |
|---|---|
| Search error logs | pup logs search --query "status:error" --from 1h |
| List monitors | pup monitors list |
| Diff a monitor definition | pup monitors diff <monitor-id> monitor.json |
| Schedule monitor downtime | pup downtime create --file downtime.json |
| Open a dashboard at a live time window | pup dashboards url <dashboard-id> --from now-1h --to now --live true |
| Find recent slow traces for a service (last 1h) | pup traces search --query "service:<service-name> @duration:>500ms" --from 1h |
| List incidents | pup incidents list --limit 50 |
| Import incident payload | pup incidents import --file incident.json |
| Query metrics | pup metrics query --query "avg:system.cpu.user{*}" |
| List hosts | pup infrastructure hosts list --count 50 |
| Check SLOs | pup slos list |
| On-call teams | pup on-call teams list |
| Triage open critical security signals (last 1h) | pup security signals list --query "status:open severity:critical" --from 1h --limit 100 |
| Search audit logs | pup audit-logs search --query "@action:deleted" --from 24h |
| Audit activity by user | pup audit-logs search --query "@usr.email:user@example.com" --from 7d |
| Investigate API key | pup audit-logs search --query "@metadata.api_key.id:KEY_ID" --from 90d |
| Check auth | pup auth status |
| Token expiry (time left) | pup auth status |
| Refresh token | pup auth refresh |
Prerequisites
Install pup using the setup instructions.
Required Input Resolution
For commands that need specific scope values (<env>, <service-name>, <team-id>, resource IDs), use this order:
- Check context first (conversation history, prior command output, saved variables).
- If missing, run a discovery command first (list/search) to get valid values.
- If still missing or ambiguous, ask the user to confirm the exact value.
- Then run the target command.
- Never run commands with unresolved placeholders like
<env>or<monitor-id>.
Auth
pup auth login # OAuth2 browser flow (recommended)
pup auth status # Check token validity
pup auth refresh # Refresh expired token (no browser)
pup auth logout # Clear credentials
Tokens expire (~1 hour). If a command fails with 401/403 mid-conversation:
pup auth refresh # Try refresh first
pup auth login # If refresh fails, full re-auth
If Chrome opens the wrong profile/window, use the one-time OAuth URL printed by pup auth login
(If the browser doesn't open, visit: ...) and open that link manually in the correct account session.
Headless/CI (no browser)
# Use env vars or:
export DD_API_KEY=your-api-key
export DD_APP_KEY=your-app-key
export DD_SITE=datadoghq.com # or datadoghq.eu, etc.
Command Reference
Monitors
pup monitors list --limit 10
pup monitors list --tags "env:<env>"
pup monitors get <monitor-id>
pup monitors search --query "<monitor-name>"
pup monitors create --file monitor.json
pup monitors update <monitor-id> --file monitor.json
pup monitors diff <monitor-id> monitor.json
pup monitors delete <monitor-id>
# No pup monitors mute/unmute commands; use downtime payloads instead.
pup downtime create --file downtime.json
Logs
pup logs search --query "status:error" --from 1h
pup logs search --query "service:<service-name>" --from 1h --limit 100
pup logs search --query "@http.status_code:5*" --from 24h
pup logs search --query "env:<env> level:error" --from 1h
pup logs aggregate --query "service:<service-name>" --compute count --from 1h
Metrics
pup metrics query --query "avg:system.cpu.user{*}" --from 1h --to now
pup metrics query --query "sum:trace.express.request.hits{service:<service-name>}" --from 1h --to now
pup metrics list --filter "system.*"
APM / Traces
# Confirm env tag with the user first (do not assume production/prod/prd).
pup apm services list --env <env> --from 1h --to now
pup traces search --query "service:<service-name>" --from 1h
pup traces search --query "service:<service-name> @duration:>500ms" --from 1h
pup traces search --query "service:<service-name> status:error" --from 1h
Incidents
pup incidents list --limit 50
pup incidents get <incident-id>
pup incidents import --file incident.json
Dashboards
pup dashboards list
pup dashboards get <dashboard-id> --read-only
pup dashboards url <dashboard-id> --from now-1h --to now --live true
pup dashboards create --file dashboard.json
pup dashboards update <dashboard-id> --file dashboard.json
pup dashboards delete <dashboard-id>
Safe dashboard create, clone, and update workflow
The goal is a recoverable source and a verified destination. A successful API response alone does not prove that widget content or placement was preserved.
- Fetch the source or update target with
--read-onlyand save the exact response as an immutable snapshot. Never overwrite this file with transformed JSON.pup dashboards get <dashboard-id> --read-only -o json > dashboard-source.json - Build a separate mutation payload. Remove response-only fields before create/update:
author_handle,author_name,created_at,id,modified_at, andurl.jq 'del(.author_handle, .author_name, .created_at, .id, .modified_at, .url)' \ dashboard-source.json > dashboard-payload.json - For a backup or clone, leave the source dashboard unchanged and change only explicitly requested fields, usually
titleordescription. Preservelayout_type,reflow_type, widget order, and every recursive widgetlayoutobject (x,y,width,height, andis_column_break). Repacking or compacting coordinates creates a derived layout, not an exact clone. - Create or update from
dashboard-payload.json, then fetch the destination into a new file.pup dashboards create --file dashboard-payload.json pup dashboards get <destination-id> --read-only -o json > dashboard-destination.json - Normalize away the response-only fields and compare the complete definitions. The only differences should be the fields intentionally changed.
- Also compare layout projections separately so a placement regression cannot hide in a large widget diff:
jq '{layout_type, reflow_type, layouts: [.. | objects | .layout? // empty]}' dashboard-source.json jq '{layout_type, reflow_type, layouts: [.. | objects | .layout? // empty]}' dashboard-destination.json
Pup 1.6.3 does not expose dashboard version history. If an exact historical version is required and no immutable snapshot exists, inspect version history in the Datadog UI before changing the dashboard.
SLOs
pup slos list
pup slos get <slo-id>
pup slos status <slo-id> --from 30d --to now
pup slos create --file slo.json
Synthetics
pup synthetics tests list
pup synthetics tests get <test-id>
pup synthetics tests search --text "login"
pup synthetics locations list
On-Call
pup on-call teams list
# Pick a real team id from `pup on-call teams list` output.
pup on-call teams get <team-id>
pup on-call teams memberships list <team-id>
Hosts / Infrastructure
pup infrastructure hosts list --count 50
pup infrastructure hosts list --filter "env:<env>"
pup infrastructure hosts get <host-name>
Events
pup events list --from 24h
pup events list --tags "source:deploy"
pup events search --query "deploy" --from 24h --limit 50
pup events get <event-id>
Downtimes
pup downtime list
pup downtime create --file downtime.json
pup downtime cancel <downtime-id>
Users / Teams
pup users list
pup users get <user-id>
Security
pup security signals list --query "*" --from 1h --limit 100
pup security signals list --query "status:open severity:critical" --from 1h --limit 100
# Broader lookback for historical triage
pup security signals list --query "severity:critical" --from 24h --limit 100
Audit Logs
# List recent events
pup audit-logs list --from 1h --limit 100
# Search with query (Lucene syntax, same as Log Explorer)
pup audit-logs search --query "@action:deleted" --from 24h
pup audit-logs search --query "@usr.email:user@example.com" --from 7d
pup audit-logs search --query "@evt.name:Authentication @action:login" --from 7d
pup audit-logs search --query "@metadata.api_key.id:KEY_ID" --from 90d --limit 200
# JSON output for piping to jq
pup audit-logs search --query "@action:deleted" --from 24h -o json | jq '.data[].attributes'
# audit-logs is the long form (both work)
pup audit-logs search --query "@evt.name:Monitor @action:modified" --from 7d
Service Catalog
pup service-catalog list
pup service-catalog get <service-name>
Notebooks
pup notebooks list
pup notebooks get <notebook-id>
Workflows
pup workflows get <workflow-id>
pup workflows run <workflow-id> --payload '{"key":"value"}'
pup workflows instances list <workflow-id>
Observability Pipelines
pup obs-pipelines list --limit 50
pup obs-pipelines get <pipeline-id>
pup obs-pipelines create --file pipeline.json
pup obs-pipelines update <pipeline-id> --file pipeline.json
pup obs-pipelines delete <pipeline-id>
pup obs-pipelines validate --file pipeline.json
LLM Observability
pup llm-obs projects list
pup llm-obs projects create --file project.json
pup llm-obs experiments list
pup llm-obs experiments list --filter-project-id <project-id>
pup llm-obs experiments list --filter-dataset-id <dataset-id>
pup llm-obs experiments create --file experiment.json
pup llm-obs experiments update <experiment-id> --file experiment.json
pup llm-obs experiments delete --file delete-request.json
pup llm-obs datasets list --project-id <project-id>
pup llm-obs datasets create --project-id <project-id> --file dataset.json
pup llm-obs spans search --ml-app <ml-app-name> --from 1h --limit 20
Reference Tables
pup reference-tables list --limit 50
pup reference-tables get <table-id>
pup reference-tables create --file table.json
pup reference-tables batch-query --file query.json
Cost Cloud Configs
# AWS CUR configs
pup cost aws-config list
pup cost aws-config get <account-id>
pup cost aws-config create --file config.json
pup cost aws-config delete <account-id>
# Azure UC configs
pup cost azure-config list
pup cost azure-config get <account-id>
pup cost azure-config create --file config.json
pup cost azure-config delete <account-id>
# GCP usage cost configs
pup cost gcp-config list
pup cost gcp-config get <account-id>
pup cost gcp-config create --file config.json
pup cost gcp-config delete <account-id>
Subcommand Discovery
pup --version # Confirm installed version before documenting workarounds
pup --help # List all commands
pup <command> --help # Command-specific help
pup dashboards get <dashboard-id> --jq '{title, layout_type}' # Filter output before formatting
If local help differs from this skill, compare pup --version with the latest stable release before inventing a workaround.
Error Handling
| Error | Cause | Fix |
|---|---|---|
| 401 Unauthorized | Token expired | pup auth refresh |
| 403 Forbidden | Missing scope | Check app key permissions |
| 404 Not Found | Wrong ID/resource | Verify resource exists |
| Rate limited | Too many requests | Add delays between calls |
Install
See Setup Pup for installation instructions.
Verify Installation
which pup
pup --version
Sites
| Site | DD_SITE value |
|---|---|
| US1 (default) | datadoghq.com |
| US3 | us3.datadoghq.com |
| US5 | us5.datadoghq.com |
| EU1 | datadoghq.eu |
| AP1 | ap1.datadoghq.com |
| AP2 | ap2.datadoghq.com |
| US1-FED | ddog-gov.com |
FAQ
What does the dd-pup skill do?
Datadog CLI (Rust). OAuth2 auth with token refresh.
How do I install dd-pup?
Run npx skills add https://github.com/datadog-labs/agent-skills --skill dd-pup in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/dd-pup/ (personal) or .claude/skills/dd-pup/ (project).
Which AI agents can use dd-pup?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is dd-pup safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk flagged items to review; Runlayer flagged items to review; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains dd-pup?
It is published by datadog-labs in datadog-labs/agent-skills, and it is an official skill from the maker of the technology it covers. It has 7,580 recorded installs.
More from datadog-labs/agent-skills
agent-skills
datadog-labs/agent-skills
Datadog skills for AI agents. Essential monitoring, logging, tracing and observability.
dd-logs
datadog-labs/agent-skills
Log management - search, archives, metrics, and cost control.
dd-apm
datadog-labs/agent-skills
APM - install, onboard, instrument, enable, set up, configure, traces, services, dependencies, performance analysis, Data Streams Monitoring (DSM), queue lag, pipeline latency. Use for any request involving Datadog APM setup, instrumentation (SSI, ddtrace, agent install), or analysis.
dd-monitors
datadog-labs/agent-skills
Monitor management - list, search, file-based create, and alerting best practices.
dd-docs
datadog-labs/agent-skills
Datadog docs lookup using docs.datadoghq.com/llms.txt and linked Markdown pages.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.