npm package: @leoflores/datadog-cli
Description: A powerful command-line interface for querying Datadog logs and metrics, designed for fast debugging and incident triage
Author: Leonardo Flores
Latest version: 1.1.0

# datadog-cli

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

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![npm version](https://img.shields.io/npm/v/@leoflores/datadog-cli)](https://www.npmjs.com/package/@leoflores/datadog-cli)

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

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

Or install globally:

```bash
npm install -g @leoflores/datadog-cli
```

### Requirements

- [Bun](https://bun.sh) >= 1.0.0 (for local development)
- Datadog API key and Application key

## Setup

Set your Datadog API credentials:

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

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

## Usage

```bash
datadog <command> [subcommand] [flags]
```

### Quick Examples

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

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

### Real-time Debugging

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

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

```bash
datadog services --from 24h --pretty
```

### Metrics

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

### Dashboards

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

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

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

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

```bash
# 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](https://github.com/ctdio/datadog-cli).

## License

MIT License. See [LICENSE](LICENSE) for details.