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.