datadog-cli

A command-line interface for querying Datadog logs and metrics, built for fast debugging and incident triage.

About

Built so AI assistants (Claude, Cursor, etc.) can help investigate production issues directly from the terminal. Search logs, trace requests, compare error rates, and analyze patterns without leaving your workflow.

Using Claude Code? Install the plugin and let Claude debug with Datadog for you:

claude /plugin marketplace add leonardocouy/cc-datadog
claude /plugin install datadog@cc-datadog

Then just ask: "search for errors in the last hour" or "what's causing the 500s?"

Features

• Log Search - Search, filter, and aggregate logs with Datadog query syntax
• Live Tail - Stream logs in real-time as they arrive
• Trace Correlation - Find all logs for a distributed trace across services
• Context View - See logs before/after a specific event
• Error Summary - Quick breakdown of errors by service, type, and message
• Period Comparison - Compare log volumes between time periods
• Pattern Detection - Group similar log messages automatically
• Metrics Query - Query timeseries metrics
• Dashboards - List, fetch, create, update, and delete dashboards
• Dashboard Lists - Manage dashboard lists and membership
• Pretty Output - Color-coded, human-readable formatting

Installation

Run directly without installing:

npx @leoflores/datadog-cli <command>
# or
bunx @leoflores/datadog-cli <command>

Or install globally:

npm install -g @leoflores/datadog-cli

Requirements

• Bun >= 1.0.0 (for local development)
• Datadog API key and Application key

Setup

Set your Datadog API credentials:

export DD_API_KEY="your-api-key"
export DD_APP_KEY="your-app-key"

Get keys from: https://app.datadoghq.com/organization-settings/api-keys

For EU or other sites, use the --site flag:

datadog logs search --query "*" --site datadoghq.eu

Usage

datadog <command> [subcommand] [flags]

Quick Examples

# Search errors in the last hour
datadog logs search --query "status:error" --from 1h --pretty

# Stream logs in real-time
datadog logs tail --query "service:api" --pretty

# Get error summary
datadog errors --from 1h --pretty

# Compare error rates
datadog logs compare --query "status:error" --period 1h --pretty

# List dashboards
datadog dashboards list --count 25 --pretty

# List dashboard lists
datadog dashboard-lists list --pretty

Commands

Log Search & Exploration

datadog logs search --query "status:error" --from 1h --pretty
datadog logs agg --query "service:api" --facet status --from 24h --pretty

Real-time Debugging

# Live tail
datadog logs tail --query "service:api status:error" --pretty

# Trace correlation
datadog logs trace --id "abc123def456" --pretty

# Context around a timestamp
datadog logs context --timestamp "2024-01-15T10:30:00Z" --service api --before 5m --after 2m --pretty

Analysis & Triage

# Error summary
datadog errors --from 1h --pretty
datadog errors --service api --from 24h --pretty

# Pattern detection
datadog logs patterns --query "status:error" --from 1h --pretty

# Period comparison
datadog logs compare --query "status:error" --period 1h --pretty

Service Discovery

datadog services --from 24h --pretty

Metrics

datadog metrics query --query "avg:system.cpu.user{*}" --from 1h --pretty

Dashboards

# List dashboards (summaries)
datadog dashboards list --count 25 --pretty

# Get dashboard definition
datadog dashboards get --id "abc-def-ghi" --pretty

# Create dashboard (widgets JSON via stdin)
echo '[{"definition":{"type":"timeseries","requests":[{"q":"avg:system.cpu.user{*}"}]}}]' | datadog dashboards create --title "CPU" --layout ordered --pretty

Dashboard Lists

# List dashboard lists
datadog dashboard-lists list --pretty

# Show dashboards in a list
datadog dashboard-lists items --id 123 --pretty

# Add dashboard to a list
datadog dashboard-lists add-items --id 123 --dashboards '[{"type":"custom_timeboard","id":"abc-def-ghi"}]' --pretty

Export & Multi-query

# Export to file
datadog logs search --query "*" --limit 1000 --output logs.json

# Multiple queries at once
datadog logs multi --queries "errors:status:error,warnings:status:warn" --from 1h --pretty

Flags Reference

Log Flags

| Flag | Description | Default | |------|-------------|---------| | --query | Log search query | * | | --from | Start time (1h, 30m, 7d, or ISO timestamp) | 15m | | --to | End time | now | | --limit | Max logs to return | 100 | | --sort | timestamp or -timestamp | -timestamp | | --id | Trace ID (for trace command) | - | | --facet | Facet for aggregation | - | | --service | Filter by service | - | | --timestamp | Target timestamp (for context) | - | | --before | Context: time before target | 5m | | --after | Context: time after target | 5m | | --interval | Tail: poll interval in seconds | 2 | | --period | Compare: comparison period | 1h |

Global Flags

| Flag | Description | |------|-------------| | --pretty | Human-readable output with colors | | --output | Write results to JSON file | | --site | Datadog site (e.g., datadoghq.eu) |

Dashboards Flags

| Flag | Description | |------|-------------| | --id | Dashboard id (get/update/delete) | | --title | Dashboard title (create/update) | | --layout | Dashboard layout type: ordered or free (create/update) | | --widgets | Widgets JSON array (create/update); if omitted, reads from stdin | | --description | Dashboard description (create/update) | | --read-only | Set dashboard read-only (create/update) | | --notify-list | JSON array of user handles to notify | | --template-variables | JSON array of template variables | | --count | List dashboards: page size | | --start | List dashboards: offset | | --shared | List dashboards: only shared | | --deleted | List dashboards: only deleted |

Dashboard Lists Flags

| Flag | Description | |------|-------------| | --id | Dashboard list id (number) | | --name | Dashboard list name (create/update) | | --dashboards | JSON array of {id,type} for add/update/delete items |

Time Formats

• Relative: 30m, 1h, 7d, 24h
• ISO 8601: 2024-01-15T10:30:00Z

Incident Triage Workflow

# 1. Check error summary
datadog errors --from 1h --pretty

# 2. Compare to previous period
datadog logs compare --query "status:error" --period 1h --pretty

# 3. Find error patterns
datadog logs patterns --query "status:error" --from 1h --pretty

# 4. Search specific errors
datadog logs search --query "status:error service:api" --from 1h --pretty

# 5. Get context around a timestamp
datadog logs context --timestamp "2024-01-15T10:30:00Z" --service api --pretty

# 6. Follow the trace
datadog logs trace --id "TRACE_ID" --pretty

Development

# Install dependencies
bun install

# Run the CLI
bun run start

# Run with watch mode
bun run dev

# Build standalone binary
bun run build

# Lint and format
bun run check

Acknowledgments

Inspired by ctdio/datadog-cli.

License

MIT License. See LICENSE for details.