Puppy Kit

https://github.com/wrenchai/puppy-kit
Admin
Puppy Kit is a modern Datadog CLI with 18+ command groups, Rich terminal output, and an optional MCP...
Tokens:93,759
Snippets:524
Trust Score:5.6
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup Puppy Kit

Source: https://github.com/wrenchai/puppy-kit/blob/main/CLAUDE.md

Installs all necessary dependencies, including development tools, for Puppy Kit.

```bash
uv sync --all-extras
```

--------------------------------

### Setup ddogctl Development Environment

Source: https://github.com/wrenchai/puppy-kit/blob/main/CONTRIBUTING.md

Clone the repository, create and activate a virtual environment, and install the project with development dependencies.

```bash
git clone https://github.com/srgfrancisco/ddogctl.git
cd ddogctl
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

--------------------------------

### Install Puppy Kit

Source: https://context7.com/wrenchai/puppy-kit/llms.txt

Install the puppy-kit package from PyPI. Use the `[mcp]` extra for MCP server support.

```bash
# Basic installation
pip install puppy-kit
```

```bash
# With uv package manager
uv pip install puppy-kit
```

```bash
# With MCP server support for AI agents
pip install puppy-kit[mcp]
```

--------------------------------

### Install puppy-kit with MCP support

Source: https://github.com/wrenchai/puppy-kit/blob/main/README.md

Install the package with the required extras for MCP functionality.

```bash
pip install puppy-kit[mcp]
```

--------------------------------

### Install puppy-kit

Source: https://github.com/wrenchai/puppy-kit/blob/main/README.md

Installation commands for the CLI tool using pip or uv, including an optional MCP server support package.

```bash
pip install puppy-kit
```

```bash
uv pip install puppy-kit
```

```bash
pip install puppy-kit[mcp]
```

--------------------------------

### Update incident attachment setup

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Initial imports and setup for updating an incident attachment.

```python
"""
Update incident attachment returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.incidents_api import IncidentsApi
from datadog_api_client.v2.model.incident_attachment_type import IncidentAttachmentType
from datadog_api_client.v2.model.patch_attachment_request import PatchAttachmentRequest
from datadog_api_client.v2.model.patch_attachment_request_data import PatchAttachmentRequestData
from datadog_api_client.v2.model.patch_attachment_request_data_attributes import PatchAttachmentRequestDataAttributes
from datadog_api_client.v2.model.patch_attachment_request_data_attributes_attachment import (
    PatchAttachmentRequestDataAttributesAttachment,
)

# there is a valid "incident" in the system
INCIDENT_DATA_ID = environ["INCIDENT_DATA_ID"]
```

--------------------------------

### Run the example script

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Command to execute the Python script with required Datadog authentication environment variables.

```bash
DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
```

--------------------------------

### Quick Start Commands

Source: https://github.com/wrenchai/puppy-kit/blob/main/README.md

Commonly used commands for managing monitors, incidents, logs, APM, metrics, and dashboards.

```bash
# 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
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
```

--------------------------------

### Investigation Commands Example

Source: https://github.com/wrenchai/puppy-kit/blob/main/reports/_template.html

This is a placeholder for commands used during an investigation. It's presented as a shell script example.

```shell
# Commands used during investigation
[COMMAND 1]
[COMMAND 2]
```

--------------------------------

### Verify project installation and quality

Source: https://github.com/wrenchai/puppy-kit/blob/main/TRANSFORMATION.md

Run these commands to synchronize dependencies, execute tests, lint code, and verify the CLI tool functionality.

```bash
uv sync
uv run pytest tests/ -v
uv run ruff check puppy_kit/ tests/
uv run ruff format --check puppy_kit/ tests/
uv run puppy --help
```

--------------------------------

### Development workflow commands

Source: https://github.com/wrenchai/puppy-kit/blob/main/README.md

Standard commands for cloning, installing dependencies, testing, linting, and running the CLI during development.

```bash
# 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

# 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
```

--------------------------------

### Datadog Client Instantiation

Source: https://github.com/wrenchai/puppy-kit/blob/main/CLAUDE.md

Shows how to get a Datadog API client instance using the `get_datadog_client` function.

```python
get_datadog_client()
```

--------------------------------

### Common CLI usage examples

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/ops-modes.md

Demonstrates standard operations including listing incidents, searching logs, querying metrics, and formatting output.

```bash
# List incidents
puppy incident list

# Search logs
puppy logs search "status:error" --service my-api --verbose

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

# Export as JSON
puppy monitor list --format json

# Validate configuration
puppy config test
```

--------------------------------

### Run Puppy Kit CLI Commands

Source: https://github.com/wrenchai/puppy-kit/blob/main/CLAUDE.md

Examples of running various Puppy Kit CLI commands, including setting environment variables for authentication.

```bash
export DD_API_KEY=... DD_APP_KEY=...
```

```bash
uv run puppy monitor list --state Alert
```

```bash
uv run puppy apm services
```

```bash
uv run puppy logs search "status:error" --service my-api
```

```bash
uv run puppy investigate latency my-service --threshold 500
```

```bash
uv run puppy monitor list --state Alert --watch 10
```

--------------------------------

### Configure ddogctl Profiles

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/plans/2026-02-12-ddogctl-roadmap-design.md

Commands for initializing, setting, using, listing, and getting configuration profiles. Supports API keys, app keys, and site selection.

```bash
ddogctl config init                           # interactive setup
```

```bash
ddogctl config set-profile prod --api-key xxx --app-key yyy --site us
```

```bash
ddogctl config set-profile staging --api-key xxx --app-key yyy --site eu
```

```bash
ddogctl config use-profile prod               # set default
```

```bash
ddogctl config list-profiles
```

```bash
ddogctl config get site                       # show current value
```

```bash
ddogctl --profile staging monitor list        # per-command override
```

--------------------------------

### Initialize puppy-kit configuration

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/ops-modes.md

Initializes the configuration file and prompts for Datadog API credentials.

```bash
puppy config init
```

--------------------------------

### Initialize DatadogClient and List Monitors

Source: https://context7.com/wrenchai/puppy-kit/llms.txt

Initializes the DatadogClient using loaded configuration and lists monitors, printing their ID, name, and state. Requires 'puppy_kit.config' and 'puppy_kit.client' imports.

```python
from puppy_kit.config import load_config
from puppy_kit.client import DatadogClient

# Load configuration (from env vars or profiles)
config = load_config(profile="production")

# Create client
with DatadogClient(config) as client:
    # List monitors
    monitors = client.monitors.list_monitors()
    for m in monitors:
        print(f"{m.id}: {m.name} - {m.overall_state}")
```

--------------------------------

### GET /api/v2/incidents/config/notification-rules

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Lists all incident notification rules.

```APIDOC
## GET /api/v2/incidents/config/notification-rules

### Description
List incident notification rules returns "OK" response.

### Method
GET

### Endpoint
/api/v2/incidents/config/notification-rules

### Request Example
```python
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.incidents_api import IncidentsApi

configuration = Configuration()
configuration.unstable_operations["list_incident_notification_rules"] = True
with ApiClient(configuration) as api_client:
    api_instance = IncidentsApi(api_client)
    response = api_instance.list_incident_notification_rules()

    print(response)
```
```

--------------------------------

### GET /api/v2/incidents/config/notification-rules

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Lists all incident notification rules for the organization.

```APIDOC
## GET /api/v2/incidents/config/notification-rules

### Description
Lists all notification rules for the organization. Optionally filter by incident type. Requires the incident_notification_settings_read permission.

### Method
GET

### Endpoint
https://api.datadoghq.com/api/v2/incidents/config/notification-rules

### Parameters
#### Query Parameters
- **include** (string) - Optional - Comma-separated list of resources to include.

### Response
#### Success Response (200)
- **data** (array) - The NotificationRuleArray data.
```

--------------------------------

### Initialize and Validate Configuration

Source: https://github.com/wrenchai/puppy-kit/blob/main/README.md

Commands to interactively set up credentials and verify connectivity to the Datadog API.

```bash
puppy config init
```

```bash
puppy config test
```

--------------------------------

### GET /incident_integrations

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves incident integration metadata details.

```APIDOC
## GET /incident_integrations

### Description
Get incident integration metadata details returns "OK" response.

### Method
GET

### Endpoint
/incident_integrations

### Response
#### Success Response (200)
- **data** (object) - User object returned by the API.
- **attributes** (object) - Attributes of user object including created_at, disabled, email, handle, icon, last_login_time, mfa_enabled, modified_at, name, service_account, status, title, verified, and id.
- **relationships** (object) - Relationships of the user object including org, other_orgs, other_users, and roles.
```

--------------------------------

### Get a postmortem template

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves the details of a specific postmortem template by its ID.

```python
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.incidents_api import IncidentsApi

configuration = Configuration()
configuration.unstable_operations["get_incident_postmortem_template"] = True
with ApiClient(configuration) as api_client:
    api_instance = IncidentsApi(api_client)
    response = api_instance.get_incident_postmortem_template(
        template_id="template-456",
    )

    print(response)
```

--------------------------------

### Get Global Incident Settings

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves the global incident settings for the organization.

```APIDOC
## GET /api/v2/incidents/config/global/settings

### Description
Retrieve global incident settings for the organization.

### Method
GET

### Endpoint
/api/v2/incidents/config/global/settings

### Response
#### Success Response (200)
- **data** (object) - Required - Global incident settings data.
  - **type** (string) - Required - Allowed enum values: "incidents_global_settings".
  - **id** (string) - Required - The unique identifier for the global incident settings.
  - **attributes** (object) - Required - Global incident settings attributes.
    - **analytics_dashboard_id** (string) - Required - The analytics dashboard ID.
    - **created** (string) - Required - Timestamp when the settings were created.
    - **modified** (string) - Required - Timestamp when the settings were last modified.

#### Response Example
```json
{
  "data": {
    "type": "incidents_global_settings",
    "id": "abc-123-def",
    "attributes": {
      "analytics_dashboard_id": "abc-123-def",
      "created": "2023-01-01T12:00:00Z",
      "modified": "2023-01-01T12:05:00Z"
    }
  }
}
```
```

--------------------------------

### Git Initialization Commands

Source: https://github.com/wrenchai/puppy-kit/blob/main/IMPLEMENTATION_PLAN.md

Commands to initialize the new repository and set up feature branches.

```bash
# Navigate to new standalone location
cd /path/to/new/location
mkdir dd-cli && cd dd-cli

# Initialize git
git init
git add .
git commit -m "chore: initial commit - dd cli with APM commands

- 176 tests, 94% coverage
- Commands: monitor, metric, event, host, apm
- Strict TDD implementation
- Ready for logs and dbm implementation"

# Create branches for new features
git checkout -b feature/logs-commands
git checkout -b feature/dbm-commands
git checkout -b feature/investigation-workflows
```

--------------------------------

### GET /incident_attachments

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves a list of incident attachments and their associated user objects.

```APIDOC
## GET /incident_attachments

### Description
List incident attachments and return the associated user objects.

### Method
GET

### Endpoint
/incident_attachments

### Response
#### Success Response (200)
- **id** (string) - Required - A unique identifier that represents the user.
- **type** (enum) - Required - Users resource type. Allowed enum values: users.
- **included** (object) - User object returned by the API.
- **attributes** (object) - Attributes of user object returned by the API.
  - **email** (string) - Email of the user.
  - **handle** (string) - Handle of the user.
  - **icon** (string) - URL of the user's icon.
  - **name** (string) - Name of the user.
  - **uuid** (string) - UUID of the user.

### Request Example
```python
from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.incidents_api import IncidentsApi

# Example usage to list incident attachments
```
```

--------------------------------

### Get Incident Details

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves the details of a specific incident using its ID.

```APIDOC
## GET /api/v2/incidents/{incident_id}

### Description
Retrieves the details of a specific incident.

### Method
GET

### Endpoint
/api/v2/incidents/{incident_id}

### Parameters
#### Path Parameters
- **incident_id** (string) - Required - The unique identifier of the incident.

### Response
#### Success Response (200)
- **data** (object) - The incident object containing details.
- **meta** (object) - Metadata about the response.

#### Response Example
```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "type": "incidents",
    "attributes": {
      "title": "Server Outage",
      "description": "The main production server is down.",
      "status": "investigating",
      "created_at": "2023-10-27T10:00:00Z",
      "updated_at": "2023-10-27T10:30:00Z"
    }
  },
  "meta": {
    "generated_at": "2023-10-27T10:35:00Z"
  }
}
```
```

--------------------------------

### GET /api/v2/incidents/{incident_id}

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves the details of a specific incident by its unique identifier.

```APIDOC
## GET /api/v2/incidents/{incident_id}

### Description
Get the details of an incident by incident_id. This endpoint requires the incident_read permission.

### Method
GET

### Endpoint
https://api.datadoghq.com/api/v2/incidents/{incident_id}

### Parameters
#### Path Parameters
- **incident_id** (string) - Required - The UUID of the incident.

#### Query Parameters
- **include** (array) - Optional - Specifies which types of related objects should be included in the response.

### Response
#### Success Response (200)
- **data** (object) - Incident data from a response.
```

--------------------------------

### Get Postmortem Template

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieve details of a specific postmortem template. This endpoint is in preview.

```APIDOC
## GET /api/v2/incidents/config/postmortem-templates/{template_id}

### Description
Retrieve details of a specific postmortem template.

### Method
GET

### Endpoint
https://api.datadoghq.com/api/v2/incidents/config/postmortem-templates/{template_id}

### Parameters
#### Path Parameters
- **template_id** (string) - Required - The ID of the postmortem template

### Response
#### Success Response (200)
- **data** (object) - 
  - **attributes** (object) - 
    - **createdAt** (date-time) - When the template was created
    - **modifiedAt** (date-time) - When the template was last modified
    - **name** (string) - The name of the template
  - **id** (string) - The ID of the template
  - **type** (enum) - Postmortem template resource type. Allowed enum values: postmortem_template

#### Response Example
```json
{
  "data": {
    "attributes": {
      "createdAt": "2023-01-01T12:00:00Z",
      "modifiedAt": "2023-01-01T12:00:00Z",
      "name": "Standard Postmortem Template"
    },
    "id": "template-456",
    "type": "postmortem_template"
  }
}
```
```

--------------------------------

### GET /api/v2/incidents/{incident_id}/attachments

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves a list of attachments associated with a specific incident.

```APIDOC
## GET /api/v2/incidents/{incident_id}/attachments

### Description
List incident attachments. This endpoint requires the incident_read permission.

### Method
GET

### Endpoint
https://api.datadoghq.com/api/v2/incidents/{incident_id}/attachments

### Parameters
#### Path Parameters
- **incident_id** (string) - Required - The UUID of the incident.

#### Query Parameters
- **filter[attachment_type]** (string) - Optional - Filter attachments by type. Supported values are 1 (postmortem) and 2 (link).
- **include** (string) - Optional - Resource to include in the response. Supported value: last_modified_by_user.

### Response
#### Success Response (200)
- **data** (array) - A list of incident attachments.
```

--------------------------------

### DBM Explain Command Implementation

Source: https://github.com/wrenchai/puppy-kit/blob/main/IMPLEMENTATION_PLAN.md

Implements the 'explain' command for DBM, allowing users to retrieve query execution plans with options for JSON or text format and metadata inclusion. Requires query_id, format, and metadata flags.

```python
def test_dbm_explain_query_plan(mock_client, runner)  # Get explain plan
def test_dbm_explain_json_format(mock_client, runner)  # JSON output
def test_dbm_explain_formatted(mock_client, runner)  # Human-readable
def test_dbm_explain_with_metadata(mock_client, runner)  # Include metadata
def test_dbm_explain_not_found(mock_client, runner)  # Query not found
```

```python
@dbm.command(name="explain")
@click.argument("query_id")
@click.option("--format", type=click.Choice(["json", "text"]), default="text")
@click.option("--include-metadata/--no-metadata", default=True)
@handle_api_error
def explain_query(query_id, format, include_metadata):
    """Get query execution plan."""
    # Show: plan, estimated cost, actual cost, indexes used
```

--------------------------------

### GET /api/v2/incidents/config/notification-rules/{id}

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves a specific incident notification rule by its unique identifier.

```APIDOC
## GET /api/v2/incidents/config/notification-rules/{id}

### Description
Retrieves a specific notification rule by its ID. This endpoint requires the incident_notification_settings_read permission.

### Method
GET

### Endpoint
/api/v2/incidents/config/notification-rules/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the notification rule.

#### Query Parameters
- **include** (string) - Optional - Comma-separated list of resources to include (created_by_user, last_modified_by_user, incident_type, notification_template).

### Response
#### Success Response (200)
- **data** (object) - Notification rule data from a response.
- **attributes** (object) - The notification rule's attributes.
- **relationships** (object) - The notification rule's resource relationships.
```

--------------------------------

### Initialize DBM API client

Source: https://github.com/wrenchai/puppy-kit/blob/main/IMPLEMENTATION_PLAN.md

Prerequisites for adding the Database Monitoring API to the client and configuring the mock.

```python
from datadog_api_client.v2.api import database_monitoring_api
self.dbm = database_monitoring_api.DatabaseMonitoringApi(self.api_client)
```

```python
client.dbm = Mock()
```

--------------------------------

### Configure Puppy Kit with Environment Variables

Source: https://context7.com/wrenchai/puppy-kit/llms.txt

Configure puppy-kit using environment variables, suitable for CI/CD pipelines. Set `DD_API_KEY`, `DD_APP_KEY`, and optionally `DD_SITE`. A specific profile can be set using `PUPPY_KIT_PROFILE` or via command-line flags.

```bash
# Required environment variables
export DD_API_KEY="your-datadog-api-key"
export DD_APP_KEY="your-datadog-application-key"
export DD_SITE="us"  # Optional: us, eu, us3, us5, ap1, gov (defaults to datadoghq.com)
```

```bash
# Use a specific profile
export PUPPY_KIT_PROFILE="production"
```

```bash
# Or specify profile per command
puppy --profile staging monitor list
```

--------------------------------

### GET /incidents/{incident_id}/todos

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves a list of todos associated with a specific incident.

```APIDOC
## GET /incidents/{incident_id}/todos

### Description
Retrieves a list of todos for a given incident. Returns an OK response upon success.

### Method
GET

### Endpoint
/incidents/{incident_id}/todos

### Parameters
#### Path Parameters
- **incident_id** (string) - Required - The unique identifier of the incident.

### Response
#### Success Response (200)
- **meta** (object) - Metadata object containing pagination details.

#### Response Example
{
  "meta": {
    "pagination": {
      "next_offset": 10,
      "offset": 0,
      "size": 10
    }
  }
}
```

--------------------------------

### Get an SLO

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/plans/2026-02-12-ddogctl-roadmap-design.md

Retrieve a specific SLO by its ID, with options to specify the output format.

```bash
ddogctl slo get <slo_id> [--format json|table]
```

--------------------------------

### Create SLO from File

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/plans/2026-02-12-ddogctl-roadmap-design.md

Create a new SLO by providing its configuration in a JSON file.

```bash
ddogctl slo create -f slo.json
```

--------------------------------

### Get a Dashboard

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/plans/2026-02-12-ddogctl-roadmap-design.md

Retrieve a specific dashboard by its ID, with options to specify the output format.

```bash
ddogctl dashboard get <dashboard_id> [--format json|table]
```

--------------------------------

### Get Incident Notification Template

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves a specific notification template by its ID. This endpoint is in Preview.

```APIDOC
## GET /api/v2/incidents/config/notification-templates/{id}

### Description
Retrieves a specific notification template by its ID.

### Method
GET

### Endpoint
/api/v2/incidents/config/notification-templates/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the notification template.

#### Query Parameters
- **include** (string) - Optional - Comma-separated list of relationships to include. Supported values: created_by_user, last_modified_by_user, incident_type

### Response
#### Success Response (200)
- **data** (object) - Required - Notification template data from a response.
  - **id** (uuid) - Required - The unique identifier of the notification template.
  - **type** (enum) - Required - Notification templates resource type. Allowed enum values: notification_templates
  - **attributes** (object) - The notification template's attributes.
    - **category** (string) - Required - The category of the notification template.
    - **content** (string) - Required - The content body of the notification template.
    - **created** (date-time) - Required - Timestamp when the notification template was created.
    - **modified** (date-time) - Required - Timestamp when the notification template was last modified.
    - **name** (string) - Required - The name of the notification template.
    - **subject** (string) - Required - The subject line of the notification template.
  - **relationships** (object) - The notification template's resource relationships.
    - **created_by_user** (object) - Relationship to user.
    - **incident_type** (object) - Relationship to an incident type.
    - **last_modified_by_user** (object) - Relationship to user.

#### Response Example
```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "type": "notification_templates",
    "attributes": {
      "category": "alert",
      "content": "An incident has been declared.\n\nTitle: Sample Incident Title\nSeverity: SEV-2\nAffected Services: web-service, database-service\nStatus: active\n\nPlease join the incident channel for updates.",
      "created": "2023-10-27T10:00:00Z",
      "modified": "2023-10-27T10:00:00Z",
      "name": "Example-Incident",
      "subject": "SEV-2 Incident: Sample Incident Title"
    },
    "relationships": {
      "created_by_user": {
        "data": {
          "id": "user-id-123",
          "type": "users"
        }
      },
      "incident_type": {
        "data": {
          "id": "your_incident_type_id",
          "type": "incident_types"
        }
      },
      "last_modified_by_user": {
        "data": {
          "id": "user-id-456",
          "type": "users"
        }
      }
    }
  }
}
```
```

--------------------------------

### Configure puppy-kit profiles

Source: https://github.com/wrenchai/puppy-kit/blob/main/TRANSFORMATION.md

Define API keys and site settings in the local configuration file for different environments.

```json
{
  "active_profile": "default",
  "profiles": {
    "default": { "api_key": "...", "app_key": "...", "site": "us" },
    "production": { "api_key": "...", "app_key": "...", "site": "eu" }
  }
}
```

--------------------------------

### Get incident todos endpoint

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Endpoint URL for retrieving all todos associated with a specific incident.

```http
GET https://api.datadoghq.com/api/v2/incidents/{incident_id}/relationships/todos
```

--------------------------------

### GET /api/v2/incidents/{incident_id}/relationships/integrations

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves a list of all integration metadata associated with a specific incident.

```APIDOC
## GET /api/v2/incidents/{incident_id}/relationships/integrations

### Description
Get all integration metadata for an incident. This endpoint requires the incident_read permission.

### Method
GET

### Endpoint
https://api.datadoghq.com/api/v2/incidents/{incident_id}/relationships/integrations

### Parameters
#### Path Parameters
- **incident_id** (string) - Required - The UUID of the incident.

### Response
#### Success Response (200)
- **data** (array) - An array of incident integration metadata.

#### Response Example
{
  "data": [
    {
      "id": "string",
      "type": "incident_integrations",
      "attributes": {
        "incident_id": "string",
        "integration_type": 1,
        "metadata": {},
        "status": 0
      }
    }
  ]
}
```

--------------------------------

### Create an incident integration metadata

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Initializes the client and imports necessary models to create incident integration metadata.

```python
from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.incidents_api import IncidentsApi
from datadog_api_client.v2.model.incident_integration_metadata_attributes import IncidentIntegrationMetadataAttributes
from datadog_api_client.v2.model.incident_integration_metadata_create_data import IncidentIntegrationMetadataCreateData
from datadog_api_client.v2.model.incident_integration_metadata_create_request import (
    IncidentIntegrationMetadataCreateRequest,
)
from datadog_api_client.v2.model.incident_integration_metadata_type import IncidentIntegrationMetadataType
from datadog_api_client.v2.model.slack_integration_metadata import SlackIntegrationMetadata
from datadog_api_client.v2.model.slack_integration_metadata_channel_item import SlackIntegrationMetadataChannelItem
```

--------------------------------

### GET /api/v2/incidents/search

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Search for incidents matching a specific query. This endpoint requires the incident_read permission.

```APIDOC
## GET /api/v2/incidents/search

### Description
Search for incidents matching a certain query. This endpoint requires the incident_read permission.

### Method
GET

### Endpoint
https://api.datadoghq.com/api/v2/incidents/search

### Parameters
#### Query Parameters
- **include** (enum) - Optional - Specifies which types of related objects should be included in the response. Allowed values: users, attachments.
- **query** (string) - Required - Specifies which incidents should be returned. The query can contain incident facets joined by ANDs/ORs.
- **sort** (enum) - Optional - Specifies the order of returned incidents. Allowed values: created, -created.
- **page[size]** (integer) - Optional - Size for a given page. The maximum allowed value is 100.
- **page[offset]** (integer) - Optional - Specific offset to use as the beginning of the returned page.

### Response
#### Success Response (200)
- **data** (object) - Data returned by an incident search.
- **facets** (object) - Facet data for incidents returned by a search query.
```

--------------------------------

### DBM Samples Command Implementation

Source: https://github.com/wrenchai/puppy-kit/blob/main/IMPLEMENTATION_PLAN.md

Implements the 'samples' command for DBM to retrieve sample executions of a query. Supports filtering by time range, limiting results, and outputting in JSON or table format. Requires query_id and accepts optional time, limit, and format parameters.

```python
def test_dbm_samples_list(mock_client, runner)  # List samples
def test_dbm_samples_json_format(mock_client, runner)  # JSON output
def test_dbm_samples_table_format(mock_client, runner)  # Table output
def test_dbm_samples_with_limit(mock_client, runner)  # Limit samples
def test_dbm_samples_time_range(mock_client, runner)  # Time filtering
def test_dbm_samples_empty(mock_client, runner)  # No samples
```

```python
@dbm.command(name="samples")
@click.argument("query_id")
@click.option("--from", "from_time", default="1h")
@click.option("--to", "to_time", default="now")
@click.option("--limit", default=10, type=int)
@click.option("--format", type=click.Choice(["json", "table"]), default="table")
@handle_api_error
def query_samples(query_id, from_time, to_time, limit, format):
    """Get sample executions of a query."""
    # Show: timestamp, duration, rows_affected, parameters
```

```python
def create_mock_dbm_sample(timestamp, duration_ms, rows_affected, params):
    """Factory for mock DBM query sample objects."""
    class MockDBMSample:
        def __init__(self):
            self.timestamp = timestamp
            self.duration = duration_ms * 1_000_000  # ns
            self.rows_affected = rows_affected
            self.parameters = params
    return MockDBMSample()
```

--------------------------------

### Get Incidents

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves a list of incidents for the user's organization. This endpoint is in public beta.

```APIDOC
## GET /api/v2/incidents

### Description
Get all incidents for the user’s organization. This endpoint requires the `incident_read` permission.

### Method
GET

### Endpoint
https://api.datadoghq.com/api/v2/incidents

### Parameters
#### Query Parameters
- **include** (array) - Specifies which types of related objects should be included in the response.
- **page[size]** (integer) - Size for a given page. The maximum allowed value is 100.
- **page[offset]** (integer) - Specific offset to use as the beginning of the returned page.

### Response
#### Success Response (200)
- **data** (array) - An array of incidents.
  - **attributes** (object) - The incident's attributes from a response.
    - **archived** (date-time) - Timestamp of when the incident was archived.
    - **case_id** (int64) - The incident case id.
    - **created** (date-time) - Timestamp when the incident was created.
    - **customer_impact_duration** (int64) - Length of the incident's customer impact in seconds.
    - **customer_impact_end** (date-time) - Timestamp when customers were no longer impacted by the incident.
    - **customer_impact_scope** (string) - A summary of the impact customers experienced during the incident.
    - **customer_impact_start** (date-time) - Timestamp when customers began being impacted by the incident.
    - **customer_impacted** (boolean) - A flag indicating whether the incident caused customer impact.
    - **declared** (date-time) - Timestamp when the incident was declared.
    - **declared_by** (object) - Incident's non Datadog creator.
      - **image_48_px** (string) - Non Datadog creator 48px image.
      - **name** (string) - Non Datadog creator name.
    - **declared_by_uuid** (string) - UUID of the user who declared the incident.
    - **detected** (date-time) - Timestamp when the incident was detected.
    - **fields** (object) - A condensed view of the user-defined fields attached to incidents.
    - **incident_type_uuid** (string) - A unique identifier that represents an incident type.
    - **is_test** (boolean) - A flag indicating whether the incident is a test incident.
    - **modified** (date-time) - Timestamp when the incident was last modified.
    - **non_datadog_creator** (object) - Incident's non Datadog creator.
      - **image_48_px** (string) - Non Datadog creator 48px image.
      - **name** (string) - Non Datadog creator name.
    - **notification_handles** (array) - Notification handles that will be notified of the incident during update.
      - **display_name** (string) - The name of the notified handle.
      - **handle** (string) - The handle used for the notification.
    - **public_id** (int64) - The monotonically increasing integer ID for the incident.
    - **resolved** (date-time) - Timestamp when the incident's state was last changed from active or stable to resolved or completed.
    - **severity** (enum) - The incident severity. Allowed enum values: UNKNOWN,SEV-0,SEV-1,SEV-2,SEV-3,SEV-4,SEV-5
    - **state** (string) - The state incident.
    - **time_to_detect** (int64) - Time to detect in seconds.

#### Response Example
```json
{
  "data": [
    {
      "type": "incident",
      "id": "incident-id-123",
      "attributes": {
        "title": "Example Incident",
        "created": "2023-10-27T09:00:00Z",
        "customer_impact_start": "2023-10-27T09:05:00Z",
        "customer_impact_end": "2023-10-27T09:30:00Z",
        "customer_impacted": true,
        "severity": "SEV-2",
        "state": "RESOLVED"
      }
    }
  ],
  "meta": {
    "page": {
      "total": 1,
      "size": 10,
      "offset": 0
    }
  }
}
```
```

--------------------------------

### Project File Structure

Source: https://github.com/wrenchai/puppy-kit/blob/main/IMPLEMENTATION_PLAN.md

Overview of new and modified files required for the implementation phases.

```text
dd/commands/logs.py          # ~300 lines
dd/commands/dbm.py           # ~350 lines
dd/commands/investigate.py   # ~400 lines
tests/commands/test_logs.py  # ~600 lines (23 tests)
tests/commands/test_dbm.py   # ~650 lines (24 tests)
tests/commands/test_investigate.py  # ~500 lines (20 tests)
```

```text
dd/client.py                 # Add logs, dbm APIs
dd/cli.py                    # Register new command groups
tests/conftest.py            # Add mock factories
```

--------------------------------

### Create a Dashboard

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/plans/2026-02-12-ddogctl-roadmap-design.md

Create a new dashboard. Supports creating from a JSON file or using inline flags for metadata like title and description.

```bash
ddogctl dashboard create -f dashboard.json
```

```bash
ddogctl dashboard create --title "My Dashboard" --layout-type ordered --description "..."
```

--------------------------------

### Get Datadog SLO Details

Source: https://context7.com/wrenchai/puppy-kit/llms.txt

Retrieves details for a specific Datadog SLO using its ID.

```python
dd_slos_get(slo_id="abc123")
```

--------------------------------

### Get Datadog Dashboard Details

Source: https://context7.com/wrenchai/puppy-kit/llms.txt

Retrieves details for a specific Datadog dashboard using its ID.

```python
dd_dashboards_get(dashboard_id="abc-def-123")
```

--------------------------------

### Manage Puppy Kit Profiles

Source: https://context7.com/wrenchai/puppy-kit/llms.txt

Manage multiple Datadog environments using named configuration profiles. Commands include setting, switching, listing, and getting profile configurations.

```bash
# Create or update a profile
puppy config set-profile prod --api-key xxx --app-key yyy --site us
```

```bash
# Switch active profile
puppy config use-profile staging
```

```bash
# List all configured profiles
puppy config list-profiles
# Output table showing: Name, API Key (masked), App Key (masked), Site, Ops Profile
```

```bash
# Get specific config value
puppy config get site
puppy config get active_profile
```

--------------------------------

### Configure via environment variables

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/ops-modes.md

Sets credentials via environment variables for temporary or scripted access.

```bash
export DD_API_KEY="..."
export DD_APP_KEY="..."
export DD_SITE="us"  # optional, defaults to datadoghq.com
puppy incident list
```

--------------------------------

### Get Datadog Incident Details

Source: https://context7.com/wrenchai/puppy-kit/llms.txt

Retrieves details for a specific Datadog incident using its ID.

```python
dd_incidents_get(incident_id="abc123")                  # Get incident details
```

--------------------------------

### Get Datadog Monitor Details

Source: https://context7.com/wrenchai/puppy-kit/llms.txt

Retrieves details for a specific Datadog monitor using its ID.

```python
dd_monitors_get(monitor_id=12345)                       # Get monitor details
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/wrenchai/puppy-kit/blob/main/README.md

Set required Datadog API and Application keys as environment variables for authentication.

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

--------------------------------

### Configure MCP Server

Source: https://context7.com/wrenchai/puppy-kit/llms.txt

JSON configuration for setting up the MCP server for AI assistants.

```json
{
  "mcpServers": {
    "puppy-kit": {
      "command": "python",
      "args": ["-m", "puppy_kit.mcp.server"],
      "env": {
        "DD_API_KEY": "your-api-key",
        "DD_APP_KEY": "your-app-key",
        "DD_SITE": "datadoghq.com"
      }
    }
  }
}
```

--------------------------------

### GET /api/v2/incidents/config/types/{incident_type_id}

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves the details of a specific incident type. Requires the incident_read authorization scope.

```APIDOC
## GET /api/v2/incidents/config/types/{incident_type_id}

### Description
Retrieves the details of a specific incident type.

### Method
GET

### Endpoint
/api/v2/incidents/config/types/{incident_type_id}

### Parameters
#### Path Parameters
- **incident_type_id** (string) - Required - The UUID of the incident type.

### Response
#### Success Response (200)
- **data** (object) - Incident type response data.
```

--------------------------------

### TDD Workflow - Test Execution

Source: https://github.com/wrenchai/puppy-kit/blob/main/IMPLEMENTATION_PLAN.md

Demonstrates the TDD workflow for command implementation, including writing failing tests (RED), implementing minimal code to pass (GREEN), refactoring, and verifying coverage. Commands include running individual tests, all tests, and coverage reports.

```bash
pytest tests/commands/test_<module>.py::<test_name> -v
```

```bash
pytest tests/ -v
```

```bash
pytest tests/commands/test_<module>.py --cov=dd.commands.<module> --cov-report=term-missing
```

--------------------------------

### Get a list of an incident's todos

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/incident_api.md

Retrieves the todos for a specified incident. Requires the datadog-api-client package.

```python
"""
Get a list of an incident's todos returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.incidents_api import IncidentsApi
```

--------------------------------

### Composable Piping with `ddogctl`

Source: https://github.com/wrenchai/puppy-kit/blob/main/docs/plans/2026-02-12-ddogctl-roadmap-design.md

Demonstrates how to use the `--from-stdin` flag with `ddogctl` commands to enable composable piping. This allows chaining commands together, where the output of one command serves as the input for another, especially when combined with `--format json`.

```bash
ddogctl monitor list --state Alert --format json | ddogctl monitor mute --from-stdin
```

```bash
ddogctl dashboard export abc-123 | ddogctl dashboard create --from-stdin --title "Copy"
```

```bash
echo '{"type":"metric alert","query":"..."}' | ddogctl monitor create --from-stdin
```
Tokens:
Raw