OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add datadog-labs/agent-skills --skill dd-pup
Datadog CLI (Rust). OAuth2 auth with token refresh.
npx skills add datadog-labs/agent-skills --skill dd-pup
Pup CLI for Datadog API operations. Supports OAuth2 and API key auth.
| 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 |
Install pup using the setup instructions.
For commands that need specific scope values (<env>, <service-name>, <team-id>, resource IDs), use this order:
<env> or <monitor-id>.Tokens expire (~1 hour). If a command fails with 401/403 mid-conversation:
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.
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.
--read-only and save the exact response as an immutable snapshot. Never overwrite this file with transformed JSON.
author_handle, author_name, created_at, id, modified_at, and url.
title or description. Preserve layout_type, reflow_type, widget order, and every recursive widget layout object (x, y, width, height, and is_column_break). Repacking or compacting coordinates creates a derived layout, not an exact clone.dashboard-payload.json, then fetch the destination into a new file.
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.
If local help differs from this skill, compare pup --version with the latest stable release before inventing a workaround.
| 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 |
See Setup Pup for installation instructions.
| 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 |
pup auth refresh # Try refresh first
pup auth login # If refresh fails, full re-auth# 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.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.jsonpup 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 1hpup 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.*"# 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 1hpup incidents list --limit 50
pup incidents get <incident-id>
pup incidents import --file incident.jsonpup 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>