# :dog2: Give Your Agent a Puppy: Introducing Pup CLI
[](https://github.com/DataDog/pup/actions/workflows/ci.yml)
[](https://www.rust-lang.org/)
[](LICENSE)
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!)
```bash
# 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](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](https://github.com/DataDog/pup/issues).
---
<details>
<summary><b>📊 Core Observability</b></summary>
| API Domain | Status | Pup Commands | Notes |
|------------|--------|--------------|-------|
| Metrics | ✅ | `metrics search`, `metrics query`, `metrics list`, `metrics get` | V1 and V2 APIs supported |
| Logs | ✅ | `logs search`, `logs list`, `logs aggregate` | V1 and V2 APIs supported |
| Events | ✅ | `events list`, `events search`, `events get` | Infrastructure event management |
| RUM | ✅ | `rum apps`, `rum sessions`, `rum events`, `rum aggregate`, `rum metrics`, `rum retention-filters`, `rum playlists`, `rum replay`, `rum viewership`, `rum heatmaps` | Apps, sessions, events, metrics, retention filters, replay playlists/segments/viewership, heatmaps |
| APM Services | ✅ | `apm services`, `apm entities`, `apm dependencies`, `apm flow-map` | Services stats, operations, resources; entity queries; dependencies; flow visualization |
| Traces | ✅ | `traces search`, `traces aggregate`, `traces metrics` | Span search/aggregation and span-based metric definitions |
| Profiling | ⏳ | `profiling` | Not supported in pup yet. Use the Datadog MCP server: https://docs.datadoghq.com/bits_ai/mcp_server. Enable with: https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=core,profiling |
| Database Monitoring | ✅ | `dbm samples search` | DBM query sample search |
| Session Replay | ✅ | `rum replay segments`, `rum playlists`, `rum viewership`, `rum sessions search` | Segments, playlist CRUD, viewership; discover sessions via RUM (not logs) |
</details>
<details>
<summary><b>🔔 Monitoring & Alerting</b></summary>
| API Domain | Status | Pup Commands | Notes |
|------------|--------|--------------|-------|
| Monitors | ✅ | `monitors list`, `monitors get`, `monitors delete`, `monitors search` | Full CRUD support with advanced search |
| Dashboards | ✅ | `dashboards list`, `dashboards get`, `dashboards delete`, `dashboards url` | Full management capabilities |
| SLOs | ✅ | `slos list`, `slos get`, `slos delete`, `slos status` | Full CRUD plus V2 status query |
| Synthetics | ✅ | `synthetics tests`, `synthetics locations`, `synthetics suites` | Tests, locations, and V2 suites management |
| Downtimes | ✅ | `downtime list`, `downtime get`, `downtime cancel` | Full downtime management |
| Notebooks | ✅ | `notebooks list`, `notebooks get`, `notebooks delete` | Investigation notebooks supported |
| Status Pages | ✅ | `status-pages pages`, `status-pages components`, `status-pages degradations` | **New** — Pages, components, and degradation management |
| Powerpacks | ❌ | - | Not yet implemented |
| Workflow Automation | ✅ | `workflows get`, `workflows create`, `workflows update`, `workflows delete`, `workflows run`, `workflows instances` | Full CRUD plus run and instance management (list, get, cancel) |
| Local Runbooks | ✅ | `runbooks list`, `runbooks describe`, `runbooks run`, `runbooks import`, `runbooks validate` | **New** — YAML-defined multi-step runbooks with pup/shell/http/workflow step types, variable interpolation, and reusable templates |
</details>
<details>
<summary><b>🔒 Security & Compliance</b></summary>
| API Domain | Status | Pup Commands | Notes |
|------------|--------|--------------|-------|
| Security Monitoring | ✅ | `security rules`, `security signals`, `security findings`, `security content-packs`, `security risk-scores` | Rules, signals, findings, content packs, entity risk scores |
| Cloud Security | ✅ | `security findings analyze`, `security findings schema` | DDSQL analytics for misconfigurations, identity risks, and all Cloud Security finding types |
| Application Security | ✅ | `security findings analyze`, `security asm-custom-rules`, `security asm-exclusions` | API findings via DDSQL, WAF custom rules and exclusion filters |
| Static Analysis | ✅ | `static-analysis ast`, `static-analysis custom-rulesets`, `static-analysis sca`, `static-analysis coverage` | Code security analysis |
| Audit Logs | ✅ | `audit-logs list`, `audit-logs search` | Full audit log search and listing |
| Data Governance | ✅ | `data-governance scanner-rules list` | Sensitive data scanner rules |
| Tag Governance | ✅ | `governance tag-rules list`, `governance tag-rules get`, `governance tag-rules score` | Tag rules and compliance scoring (`/api/v2/governance/tag_rules`) |
| CSM Threats | ✅ | `csm-threats` | Cloud Security Management threat rules and agent rules |
| Sensitive Data Scanner | ✅ | `data-governance scanner-rules list` | Listed via Data Governance row above |
| Agentless Scanning | ✅ | `agentless-scanning aws list/get/create/update/delete`, `agentless-scanning gcp list`, `agentless-scanning azure list` | Cloud agentless scanning configuration for AWS, GCP, and Azure |
| Logs Restriction | ✅ | `logs-restriction list`, `logs-restriction get`, `logs-restriction create`, `logs-restriction update`, `logs-restriction delete` | Log restriction queries for fine-grained log access control |
| Data Deletion | ✅ | `data-deletion requests list`, `data-deletion requests create`, `data-deletion requests cancel` | GDPR/compliance data deletion request management |
</details>
<details>
<summary><b>☁️ Infrastructure & Cloud</b></summary>
| API Domain | Status | Pup Commands | Notes |
|------------|--------|--------------|-------|
| Infrastructure | ✅ | `infrastructure hosts list`, `infrastructure hosts get` | Host inventory management |
| Tags | ✅ | `tags list`, `tags get`, `tags add`, `tags update`, `tags delete` | Host tag operations |
| Network | ✅ | `network flows list`, `network devices`, `network interfaces` | Network flows, device inventory, interface tags |
| Cloud (AWS) | ✅ | `cloud aws list`, `cloud aws cloud-auth persona-mappings` | AWS integration management with persona mapping CRUD |
| Cloud (GCP) | ✅ | `cloud gcp list` | GCP integration management |
| Cloud (Azure) | ✅ | `cloud azure list` | Azure integration management |
| Cloud (OCI) | ✅ | `cloud oci` | Oracle Cloud tenancy configs and products |
| Containers | ✅ | `containers list`, `containers images list` | Containers |
| Processes | ✅ | `processes list` | Process inventory query |
</details>
<details>
<summary><b>🚨 Incident & Operations</b></summary>
| API Domain | Status | Pup Commands | Notes |
|------------|--------|--------------|-------|
| Incidents | ✅ | `incidents list`, `incidents get`, `incidents attachments`, `incidents settings`, `incidents handles`, `incidents postmortem-templates` | Incident management with settings, handles, and postmortem templates |
| On-Call | ✅ | `on-call teams` (CRUD, memberships with roles), `on-call pages` (list, get, create) | Team management and newest-first on-call page access |
| Case Management | ✅ | `cases` (create, search, assign, archive, projects, jira, servicenow, move) | Complete case management with Jira/ServiceNow linking |
| Error Tracking | ✅ | `error-tracking issues search`, `error-tracking issues get` | Error issue search and details |
| Service Catalog | ✅ | `service-catalog list`, `service-catalog get` | Service registry management |
| Scorecards | ✅ | `scorecards list`, `scorecards get` | Service quality scores |
| Fleet Automation | ✅ | `fleet agents`, `fleet deployments`, `fleet schedules` | Agent management, deployments, schedules (Preview) |
| HAMR | ✅ | `hamr connections get`, `hamr connections create` | **New** — High Availability Multi-Region connections |
| Investigations | ✅ | `investigations list`, `investigations get`, `investigations trigger` | Bits AI SRE investigation management |
| Change Management | ✅ | `change-management create`, `change-management get`, `change-management update`, `change-management create-branch`, `change-management decisions` | Change request management with decisions and branching |
| Change Stories | ✅ | `change-stories list` | Change events for a service (deployments, feature flags, config, k8s, watchdog) over a time window |
| Incident Services/Teams | ✅ | `incidents services`, `incidents teams` | Service and team CRUD scoped to incident management |
| Live Debugger | ✅ | `debugger probes list`, `debugger probes get`, `debugger probes create`, `debugger probes delete`, `debugger probes watch` | Remote log probe management for Live Debugger |
| Software Catalog | ✅ | `software-catalog entities list`, `software-catalog entities upsert`, `software-catalog kinds list`, `software-catalog relations list` | Software Catalog entity and kind management (next-gen catalog) |
</details>
<details>
<summary><b>🔧 CI/CD & Development</b></summary>
| API Domain | Status | Pup Commands | Notes |
|------------|--------|--------------|-------|
| CI Visibility | ✅ | `cicd pipelines list`, `cicd events list` | CI/CD pipeline visibility and events |
| Test Optimization | ✅ | `cicd tests`, `cicd flaky-tests`, `test-optimization` | Test events, flaky test management, and Test Optimization API |
| DORA Metrics | ✅ | `cicd dora` | DORA deployment patching |
| Code Coverage | ✅ | `code-coverage branch-summary`, `code-coverage commit-summary` | Branch and commit-level coverage summaries |
| Deployment Gates | ✅ | `deployment-gates gates`, `deployment-gates evaluations`, `deployment-gates rules` | Deployment gate CRUD, evaluation triggers, and rule management |
</details>
<details>
<summary><b>👥 Organization & Access</b></summary>
| API Domain | Status | Pup Commands | Notes |
|------------|--------|--------------|-------|
| Users | ✅ | `users list`, `users get`, `users roles`, `users seats` | User and role management with seat assignment |
| Organizations | ✅ | `organizations get`, `organizations list` | Organization settings management |
| API Keys | ✅ | `api-keys list`, `api-keys get`, `api-keys create`, `api-keys delete` | Full API key CRUD |
| App Keys | ✅ | `app-keys list`, `app-keys get`, `app-keys create`, `app-keys update`, `app-keys delete` | Full application key CRUD |
| Service Accounts | ✅ | - | Managed via users commands |
| Roles | ❌ | - | Only list via users |
| AuthN Mappings | ✅ | `authn-mappings list`, `authn-mappings get`, `authn-mappings create`, `authn-mappings update`, `authn-mappings delete` | SAML/IdP attribute-to-role authentication mappings |
</details>
<details>
<summary><b>⚙️ Platform & Configuration</b></summary>
| API Domain | Status | Pup Commands | Notes |
|------------|--------|--------------|-------|
| Usage Metering | ✅ | `usage summary`, `usage hourly` | Usage and billing metrics |
| Cost Management | ✅ | `costs datadog projected`, `costs datadog attribution`, `costs datadog by-org`, `costs datadog aws-config`, `costs datadog azure-config`, `costs datadog gcp-config`, `costs ccm custom-costs`, `costs ccm tag-descriptions`, `costs ccm tag-metadata`, `costs ccm tags`, `costs ccm tag-keys`, `costs ccm budgets`, `costs ccm commitments` | Cost attribution, cloud cost configs (AWS/Azure/GCP), and Cloud Cost Management (custom costs, tag descriptions, budgets, commitment programs) |
| Product Analytics | ✅ | `product-analytics events send`, `product-analytics query` | Server-side product analytics events and queries |
| Integrations | ✅ | `integrations slack`, `integrations pagerduty`, `integrations webhooks`, `integrations jira`, `integrations servicenow`, `integrations google-chat`, `integrations ms-teams` | Third-party integrations including Jira, ServiceNow, Google Chat, and Microsoft Teams |
| Feature Flags | ✅ | `feature-flags flags`, `feature-flags environments`, `feature-flags allocations`, `feature-flags exposure`, `feature-flags enable`, `feature-flags disable` | Feature flag management with environment, allocation, and exposure control |
| Data Streams (Kafka) | ✅ | `kafka topic-configs`, `kafka broker-configs`, `kafka client-configs`, `kafka read-messages` | **Experimental** — Kafka cluster inspection via Datadog |
| Restricted Datasets | ✅ | `datasets list`, `datasets get`, `datasets create`, `datasets update`, `datasets delete` | Restricted dataset management for data access control |
| Observability Pipelines | ✅ | `obs-pipelines list`, `obs-pipelines get`, `obs-pipelines create`, `obs-pipelines update`, `obs-pipelines delete`, `obs-pipelines validate` | Full pipeline CRUD and validation |
| LLM Observability | ✅ | `llm-obs projects`, `llm-obs experiments`, `llm-obs datasets` | **New** — LLM Obs projects, experiments (incl. `events submit`), and dataset management (incl. `datasets records` / `records-full`) |
| Reference Tables | ✅ | `reference-tables list`, `reference-tables get`, `reference-tables create`, `reference-tables batch-query` | **New** — Reference table management for log enrichment |
| Miscellaneous | ✅ | `misc ip-ranges`, `misc status` | IP ranges and status |
| App Builder | ✅ | `app-builder list`, `app-builder get`, `app-builder create`, `app-builder update`, `app-builder delete`, `app-builder publish` | Low-code app management with publish/unpublish and batch delete |
| Key Management | ✅ | `api-keys`, `app-keys` | API key and application key CRUD (listed in Organization & Access above) |
| IP Allowlist | ❌ | - | Not yet implemented |
</details>
## Installation
### Install Script (macOS/Linux/Windows)
```bash
curl -fsSL https://raw.githubusercontent.com/DataDog/pup/main/install.sh | sh
```
On macOS with Homebrew installed, the script runs `brew install datadog-labs/pack/pup`, unless `PUP_VERSION` or `PUP_INSTALL_DIR` is set. Otherwise (Linux, macOS without Homebrew, and Windows via Git Bash, MSYS2, or Cygwin) it downloads the release archive, verifies its SHA-256 checksum, and installs the binary to `~/.local/bin`. Environment variables override the defaults:
| Variable | Default | Description |
|----------|---------|-------------|
| `PUP_VERSION` | latest release | Version to install (e.g. `1.27.0`) |
| `PUP_INSTALL_DIR` | `~/.local/bin` | Directory to install the binary into |
| `PUP_NO_BREW` | unset | Set to `1` on macOS to skip Homebrew and download directly |
```bash
curl -fsSL https://raw.githubusercontent.com/DataDog/pup/main/install.sh | PUP_VERSION=1.27.0 PUP_INSTALL_DIR=/usr/local/bin sh
```
### Homebrew (macOS/Linux)
```bash
brew tap datadog-labs/pack
brew install datadog-labs/pack/pup
```
### npm
```bash
# Run without installing
npx @datadog/pup auth login
npx @datadog/pup monitors list
# Or install globally
npm install -g @datadog/pup
```
See [npm/pup/README.md](npm/pup/README.md) for how the platform packages work.
### Build from Source
```bash
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](https://github.com/DataDog/pup/releases/latest).
## 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.
```bash
# 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
# Export the current access token to a credential-command integration
pup auth token
# 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.
```bash
# 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):
| Value | macOS | Linux | Windows | Prompts |
|---|---|---|---|---|
| `keychain` (default) | Keychain via Security framework | Secret Service (GNOME Keyring / KWallet); falls back to `file` if unavailable | WinCred (chunked) | macOS may prompt once per stable app identity (signed Homebrew release); unsigned/dev builds may prompt on each new build |
| `file` | Plaintext JSON under `~/.config/pup/`, `0600` perms | Same | Same | Never |
**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](docs/OAUTH2.md) for detailed OAuth2 documentation.
`pup auth token` prints the current OAuth access token for command-backed
integrations, refreshing a stored token when needed. It writes only the token to
stdout, is native-only, and is omitted from AI-agent schemas. Treat its output as
a secret.
### API Key Authentication (Fallback)
If OAuth2 tokens are not available, Pup automatically falls back to API key authentication.
```bash
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:
```bash
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](#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
```bash
# OAuth2 login (recommended)
pup auth login
# Check authentication status
pup auth status
# Refresh access token
pup auth refresh
# Logout
pup auth logout
```
### Test Connection
```bash
pup auth test
```
### Monitors
```bash
# List all monitors
pup monitors list
# Get specific monitor
pup monitors get 12345678
# Delete monitor
pup monitors delete 12345678 --yes
```
### Metrics
```bash
# 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
```bash
# 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
```bash
# List all SLOs
pup slos list
# Get SLO details
pup slos get abc-123
# Delete SLO
pup slos delete abc-123 --yes
```
### Incidents
```bash
# List all incidents
pup incidents list
# Get incident details
pup incidents get abc-123-def
```
### IDP Entity Graph
```bash
# Discover available entity kinds and their query schema
pup idp kinds list
pup idp kinds describe service
# Get service ownership, dependencies, and health context in one request
pup idp entities query 'kind:service AND name:"<service-name>"' \
--field name,owner,service_health_status,active_incidents_count,alert_monitors_count,breached_slos_count \
--include owner_teams,systems,upstream_services,downstream_services \
--relation-limit 3 \
--timeseries-interval 24h \
--limit 1
# Install schema-first entity graph guidance for your detected coding agent
pup skills install --name dd-idp
```
## Global Flags
- `-o, --output`: Output format (`json`, `table`, `yaml`, `csv`, or `tsv`) — 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](docs/TROUBLESHOOTING.md#override-api-endpoint).
- `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.
## AI Agents
Pup behaves the same whether a person or an AI coding agent runs it: JSON output is always wrapped in the same envelope, and `--help` is always standard text help.
```json
{
"status": "success",
"data": [ ... ],
"meta": { "page": { "after": "eyJ..." } },
"metadata": {
"command": "logs search",
"count": 50,
"truncated": true,
"next_cursor": "eyJ...",
"next_action": "More results available. Use --cursor=\"eyJ...\" ..."
}
}
```
- `data` is the command payload. When the API response has a top-level `data`, it stays in place and the response's other keys (`meta`, `links`, `included`) are kept next to it; any other response becomes `data`.
- `metadata` is always present. `truncated` says whether pup knows more results exist, and `next_cursor` / `next_offset` say where the next page starts, even after `--jq`. `next_action` names the command's own cursor flag.
- `--jq` runs on the raw API response; its result becomes `data`.
- JSON and YAML output carry the envelope. Table, CSV, and TSV print only the result rows on stdout (so CSV/TSV stay parseable) and always print the metadata to stderr as one block:
```text
metadata: command="monitors search" count=30 truncated=true next_page=1
next_action: More results available; rerun with --page=1
warning: <only when there are warnings>
```
The `metadata:` line always appears, with `key=value` pairs in a fixed order (command, count, truncated, next_cursor, next_offset, next_page; absent keys omitted, strings JSON-quoted). With `--no-envelope`, only `warning:` lines are printed.
- `--no-envelope` (or `PUP_NO_ENVELOPE=1`) prints the raw API response instead. The legacy `--no-agent` flag does the same and also turns off agent auto-approval.
Pup detects common AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, and others) from their environment variables to add an `ai-agent <name>` token to the User-Agent header for telemetry and to auto-approve CLI prompts. Detection changes nothing else: output and help are the same as for humans.
For agents and scripts:
```bash
# Machine-readable command reference (JSON)
pup agent schema
pup agent schema --compact
pup agent schema logs aggregate # One command, including its response shape
# Skip confirmation prompts for write operations
pup monitors delete 12345 --yes
```
When pup detects an AI agent, it auto-approves CLI prompts, as it does with `--yes` or `DD_AUTO_APPROVE=true`; pass `--no-agent` to keep the prompts. Agents should still get the user's explicit authorization before any remote change. The legacy `--agent` flag is accepted and ignored.
## WASM
Pup compiles to WebAssembly via the `wasm32-wasip2` target for use in WASI-compatible runtimes such as Wasmtime, Wasmer, and Cloudflare Workers.
### Building
```bash
# 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:
```bash
# 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
```bash
# 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.
```bash
# 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; `until` is evaluated against the raw payload (as `--no-envelope` prints it)
- **Output capture**: `capture: VAR_NAME` stores a pup step's raw payload (as `--no-envelope` prints it, in JSON or YAML) for use in later steps; the step's displayed output still follows your format and envelope choice
- **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](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.
```bash
# 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
pup skills install hermes
# 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/`. Codex's `CODEX_HOME` and Hermes Agent's `HERMES_HOME` are honoured the same way (user-scope installs go to `$CODEX_HOME/skills/` and `$HERMES_HOME/skills/`), since each harness reads its skills from under that directory when it is relocated. For Cursor, Codex, opencode, Devin, and Hermes, everything installs as `SKILL.md` under that tool's skills directory (e.g. `~/.cursor/skills/`, `~/.codex/skills/`, `~/.config/opencode/skills/`, Devin's `~/.agents/skills/` — or `.agents/skills/` with `--project` — and Hermes Agent's `~/.hermes/skills/` — or `.hermes/skills/` with `--project`; Hermes only loads project-local skills from repos trusted via `hermes skills trust`).
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)
# Agent Plugins format (plugin.json at the repo root, read by GitHub Copilot CLI and by
# marketplaces in that format; its version follows the CLI's release)
```
## 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](https://agentcommunicationprotocol.dev/)** — Agent Communication Protocol for ACP-native clients
- **OpenAI-compatible** — `POST /chat/completions` for [opencode](https://opencode.ai), Cursor, and any `@ai-sdk/openai-compatible` client
```bash
# 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`):
```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](docs/EXAMPLES.md) for full usage details.
## Development
```bash
# 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](CLAUDE.md).