puppy-kit

Datadog CLI for AI-driven incident management.

A modern CLI for the Datadog API with 18 command groups, Rich terminal output, retry logic, and an optional MCP server that lets AI agents detect, triage, and resolve incidents autonomously.

Features

• 18 command groups covering monitors, incidents, logs, APM, dashboards, and more
• Rich terminal output with tables, colors, and progress indicators
• Optional MCP server exposing Datadog operations as tools for AI agents
• Retry logic with exponential backoff on rate limits and server errors
• Region shortcuts (us, eu, us3, us5, ap1, gov)
• Watch mode, stdin piping, and JSON export
• --verbose flag for full output on logs, APM, and LLM commands
• Structured JSON envelope with --format json: {data, count, hint}

Installation

pip install puppy-kit

With uv:

uv tool install "puppy-kit[mcp]"

With MCP server support:

pip install puppy-kit[mcp]

Configuration

Getting Your Credentials

Before using puppy-kit, you need two API keys from Datadog:

• DD_API_KEY — Your organization's API key. Found in Datadog at Organization Settings > API Keys. This key is scoped to your organization and used for sending and reading data (metrics, logs, events, etc.).

• DD_APP_KEY — Your personal application key. Found in Datadog at Organization Settings > Application Keys. This key is scoped to your user account and is required for management operations such as creating/updating monitors, dashboards, logs queries, and other admin tasks. Granting all scopes is recommended for personal use.

Important: Both keys are required for most puppy commands. Without DD_APP_KEY, you will receive a 403 Unauthorized error on most read and write operations.

To locate these in the Datadog UI:

1. Log in to Datadog
2. Click your user icon (bottom left) → Organization Settings
3. Select API Keys or Application Keys from the left sidebar
4. Copy the key or generate a new one

Environment Variables

export DD_API_KEY="your-api-key"
export DD_APP_KEY="your-app-key"
export DD_SITE="us"  # optional, defaults to datadoghq.com

Note: DD_SITE is a shortcut (see Region Shortcuts below). For example, use us5 to point to us5.datadoghq.com.

Interactive Setup

puppy config init

This command prompts you interactively for your DD_API_KEY, DD_APP_KEY, and optional DD_SITE, then creates ~/.puppy-kit/config.json with your credentials.

Validate Configuration

Test your setup:

puppy config test

This verifies that your credentials are valid and connected to Datadog.

Region Shortcuts

Verify Connectivity

After setting up your credentials, test the connection:

puppy config get          # confirm keys are loaded
puppy monitor list        # test authenticated read

If you see a 403 Unauthorized error, ensure both DD_API_KEY and DD_APP_KEY are set and have the correct values.

Quick Start

# Monitors
puppy monitor list --state Alert
puppy monitor get 12345
puppy monitor mute 12345

# Incidents
puppy incident list
puppy incident create --title "API latency spike" --severity SEV-2 --team engineering
puppy incident update abc123 --status resolved

# Logs
puppy logs search "status:error" --service my-api --from 30m
puppy logs tail "env:prod"
puppy logs search "status:error" --verbose  # Full output

# APM
puppy apm services
puppy apm traces my-service --from 1h
puppy apm services --verbose  # Full output

# Metrics
puppy metric query "avg:system.cpu.user{env:prod}" --from 1h

# Dashboards
puppy dashboard list
puppy dashboard get abc-def-123

# Watch mode (auto-refresh)
puppy monitor list --state Alert --watch 10

# JSON export
puppy monitor list --format json

Commands

All commands support --format json for structured output with {data, count, hint} envelope.

MCP Server

puppy-kit includes an optional Model Context Protocol server that exposes Datadog operations as tools for AI agents.

Setup

Install with MCP support:

pip install "puppy-kit[mcp]"
# or
uv tool install "puppy-kit[mcp]"

Available Tools

Claude Code Integration

Add to your Claude Code MCP config (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "puppy-kit": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "puppy-kit[mcp]", "puppy-mcp"]
    }
  }
}

Credentials are read from your active puppy-kit profile (puppy config init) or from environment variables:

{
  "mcpServers": {
    "puppy-kit": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "puppy-kit[mcp]", "puppy-mcp"],
      "env": {
        "DD_API_KEY": "your-api-key",
        "DD_APP_KEY": "your-app-key",
        "DD_SITE": "us5"
      }
    }
  }
}

Development

# Clone and install
git clone https://github.com/WrenchAI/puppy-kit.git
cd puppy-kit
uv sync --all-extras

# Run tests
uv run pytest tests/ -v
uv run pytest tests/test_e2e_mcp.py -v  # live e2e tests (requires credentials)

# Lint and format
uv run ruff check puppy_kit/ tests/
uv run ruff format puppy_kit/ tests/

# Run CLI in development
uv run puppy --help

License

MIT