0
# Command-Line Tools
1

2
Comprehensive command-line interface providing access to all Datadog functionality through shell commands. Supports automation, scripting, DevOps workflows, and administrative tasks with consistent argument patterns and output formatting.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
Central command-line interface with subcommands for different Datadog services and resources.
9

10
```python { .api }
11
def main():
12
    """
13
    Main entry point for dogshell CLI commands.
14
    
15
    Available as console scripts:
16
    - dogshell: Primary CLI command
17
    - dog: Legacy CLI command (deprecated, use dogshell)
18
    - dogwrap: Command wrapper with metrics collection
19
    - dogshellwrap: Shell wrapper with metrics collection
20
    
21
    Global Options:
22
    - --config: Path to dogrc configuration file (default: ~/.dogrc)
23
    - --api-key: Datadog API key (or DATADOG_API_KEY env var)
24
    - --application-key: Datadog app key (or DATADOG_APP_KEY env var)
25
    - --pretty: Human-readable output formatting
26
    - --raw: Raw JSON output
27
    - --timeout: Request timeout in seconds (default: 10)
28
    - --api_host: Datadog site (us, eu, us3, us5, ap1, gov, or custom URL)
29
    """
30

31
# Configuration file format (~/.dogrc):
32
# [Connection]
33
# apikey = your-api-key
34
# appkey = your-app-key
35
# api_host = https://api.datadoghq.com
36
```
37

38
### Monitor Management CLI
39

40
Command-line interface for creating, updating, and managing monitors with full configuration support.
41

42
```python { .api }
43
class MonitorClient:
44
    """CLI client for monitor management operations."""
45
    
46
    # Available commands:
47
    # dogshell monitor show <monitor_id>
48
    # dogshell monitor show_all [--group_states <states>] [--tags <tags>]
49
    # dogshell monitor post --type <type> --query <query> --name <name> [options]
50
    # dogshell monitor update <monitor_id> [options]
51
    # dogshell monitor delete <monitor_id> [--force]
52
    # dogshell monitor mute <monitor_id> [--scope <scope>] [--end <timestamp>]
53
    # dogshell monitor unmute <monitor_id> [--scope <scope>]
54
    # dogshell monitor mute_all
55
    # dogshell monitor unmute_all
56
    # dogshell monitor search [--query <query>] [--page <page>] [--per_page <count>]
57
    # dogshell monitor validate --type <type> --query <query>
58
```
59

60
### Event Management CLI
61

62
Command-line tools for posting events and querying the event stream for operational awareness.
63

64
```python { .api }
65
class EventClient:
66
    """CLI client for event management operations."""
67
    
68
    # Available commands:
69
    # dogshell event post --title <title> --text <text> [options]
70
    # dogshell event show <event_id>
71
    # dogshell event stream [--start <timestamp>] [--end <timestamp>] [options]
72
    
73
    # Event post options:
74
    # --date_happened <timestamp>: When event occurred
75
    # --priority <normal|low>: Event priority
76
    # --tags <tag1,tag2>: Comma-separated tags
77
    # --alert_type <error|warning|info|success>: Alert type
78
    # --aggregation_key <key>: Aggregation key for grouping
79
    # --source_type_name <source>: Source type identifier
80
    # --host <hostname>: Host name for event
81
```
82

83
### Metrics Management CLI
84

85
Command-line interface for querying metrics data and submitting custom metrics with flexible formatting.
86

87
```python { .api }
88
class MetricClient:
89
    """CLI client for metrics operations."""
90
    
91
    # Available commands:
92
    # dogshell metric query --query <query> --from <timestamp> --to <timestamp>
93
    # dogshell metric post --metric <name> --points <points> [options]
94
    # dogshell metric list
95
    
96
    # Metric post options:
97
    # --points: JSON array of [timestamp, value] pairs
98
    # --host <hostname>: Host name for metric
99
    # --tags <tag1,tag2>: Comma-separated tags
100
    # --type <gauge|count|rate>: Metric type
101
    # --interval <seconds>: Metric interval
102
```
103

104
### Dashboard Management CLI
105

106
Command-line tools for creating and managing dashboards with widget configurations and template variables.
107

108
```python { .api }
109
class DashboardClient:
110
    """CLI client for dashboard management (v2 API)."""
111
    
112
    # Available commands:
113
    # dogshell dashboard show <dashboard_id>
114
    # dogshell dashboard show_all [--filter_shared] [--filter_deleted]
115
    # dogshell dashboard post --title <title> --widgets <widgets_json> --layout_type <type>
116
    # dogshell dashboard update <dashboard_id> [options]
117
    # dogshell dashboard delete <dashboard_id>
118

119
class TimeboardClient:
120
    """CLI client for timeboard management (v1 API, legacy)."""
121
    
122
    # Available commands:
123
    # dogshell timeboard show <timeboard_id>
124
    # dogshell timeboard show_all
125
    # dogshell timeboard post --title <title> --graphs <graphs_json>
126
    # dogshell timeboard update <timeboard_id> [options]
127
    # dogshell timeboard delete <timeboard_id>
128

129
class ScreenboardClient:
130
    """CLI client for screenboard management (v1 API, legacy)."""
131
    
132
    # Available commands:
133
    # dogshell screenboard show <screenboard_id>
134
    # dogshell screenboard show_all
135
    # dogshell screenboard post --board_title <title> --widgets <widgets_json>
136
    # dogshell screenboard update <screenboard_id> [options]
137
    # dogshell screenboard delete <screenboard_id>
138
    # dogshell screenboard share <screenboard_id>
139
```
140

141
### Infrastructure Management CLI
142

143
Command-line interface for host management, tagging, and infrastructure monitoring operations.
144

145
```python { .api }
146
class HostClient:
147
    """CLI client for individual host operations."""
148
    
149
    # Available commands:
150
    # dogshell host mute <hostname> [--end <timestamp>] [--message <message>] [--override]
151
    # dogshell host unmute <hostname>
152

153
class HostsClient:
154
    """CLI client for host management operations."""
155
    
156
    # Available commands:
157
    # dogshell hosts search [--filter <filter>] [--sort_field <field>] [--sort_dir <asc|desc>]
158
    # dogshell hosts show_all
159
    # dogshell hosts totals
160

161
class TagClient:
162
    """CLI client for tag management operations."""
163
    
164
    # Available commands:
165
    # dogshell tag show <hostname> [--source <source>]
166
    # dogshell tag add <hostname> <tag1> <tag2> ... [--source <source>]
167
    # dogshell tag replace <hostname> <tag1> <tag2> ... [--source <source>]
168
    # dogshell tag detach <hostname> [--source <source>]
169
    # dogshell tag show_all [--source <source>]
170
```
171

172
### Downtime Management CLI
173

174
Command-line tools for scheduling and managing downtime periods with flexible scoping and recurrence.
175

176
```python { .api }
177
class DowntimeClient:
178
    """CLI client for downtime management operations."""
179
    
180
    # Available commands:
181
    # dogshell downtime show <downtime_id>
182
    # dogshell downtime show_all [--current_only]
183
    # dogshell downtime post --scope <scope> [options]
184
    # dogshell downtime update <downtime_id> [options]
185
    # dogshell downtime cancel <downtime_id>
186
    
187
    # Downtime post options:
188
    # --scope: JSON array of scope tags
189
    # --start <timestamp>: Start time (optional, defaults to now)
190
    # --end <timestamp>: End time (optional for indefinite)
191
    # --message <message>: Downtime message
192
    # --timezone <tz>: Timezone identifier
193
    # --recurrence <recurrence_json>: Recurrence configuration
194
    # --monitor_id <id>: Specific monitor to mute
195
    # --monitor_tags <tags>: Monitor tags to match
196
```
197

198
### Service Level Objectives CLI
199

200
Command-line interface for creating and managing SLOs with threshold configuration and history tracking.
201

202
```python { .api }
203
class ServiceLevelObjectiveClient:
204
    """CLI client for SLO management operations."""
205
    
206
    # Available commands:
207
    # dogshell service_level_objective show <slo_id>
208
    # dogshell service_level_objective show_all [options]
209
    # dogshell service_level_objective post --name <name> --type <type> --query <query> [options]
210
    # dogshell service_level_objective update <slo_id> [options]
211
    # dogshell service_level_objective delete <slo_id> [--force]
212
    # dogshell service_level_objective history <slo_id> --from <timestamp> --to <timestamp>
213
    
214
    # SLO post options:
215
    # --thresholds: JSON array of threshold configurations
216
    # --timeframe <7d|30d|90d>: Time window
217
    # --target_threshold <float>: Target percentage (0-100)
218
    # --warning_threshold <float>: Warning percentage
219
    # --description <text>: SLO description
220
    # --tags <tag1,tag2>: Comma-separated tags
221
```
222

223
### Search and Discovery CLI
224

225
Command-line tools for searching across Datadog resources and discovering available data.
226

227
```python { .api }
228
class SearchClient:
229
    """CLI client for search operations across Datadog resources."""
230
    
231
    # Available commands:
232
    # dogshell search query <query_string> [--facets <facets>]
233
    # dogshell search metrics <query> [--limit <limit>]
234
    # dogshell search hosts <query> [--limit <limit>]
235
    # dogshell search tags <query> [--limit <limit>]
236
```
237

238
### Service Check CLI
239

240
Command-line interface for submitting service check status and health information.
241

242
```python { .api }
243
class ServiceCheckClient:
244
    """CLI client for service check operations."""
245
    
246
    # Available commands:
247
    # dogshell service_check check --check <name> --status <status> [options]
248
    
249
    # Service check options:
250
    # --status <0|1|2|3>: Check status (OK, WARNING, CRITICAL, UNKNOWN)
251
    # --timestamp <timestamp>: Check timestamp
252
    # --hostname <hostname>: Host name
253
    # --tags <tag1,tag2>: Comma-separated tags
254
    # --message <message>: Check message
255
```
256

257
### Security Monitoring CLI
258

259
Command-line tools for managing security monitoring rules and signals.
260

261
```python { .api }
262
class SecurityMonitoringClient:
263
    """CLI client for security monitoring operations."""
264
    
265
    # Available commands:
266
    # dogshell security_monitoring show <rule_id>
267
    # dogshell security_monitoring show_all
268
    # dogshell security_monitoring post --name <name> --queries <queries_json> [options]
269
    # dogshell security_monitoring update <rule_id> [options]  
270
    # dogshell security_monitoring delete <rule_id>
271
    # dogshell security_monitoring search_signals [options]
272
```
273

274
### Comment Management CLI
275

276
Command-line interface for creating and managing comments on graphs and dashboards.
277

278
```python { .api }
279
class CommentClient:
280
    """CLI client for comment management operations."""
281
    
282
    # Available commands:
283
    # dogshell comment show <comment_id>
284
    # dogshell comment post --message <message> [--handles <handles>]
285
    # dogshell comment update <comment_id> --message <message> [--handles <handles>]
286
    # dogshell comment reply <comment_id> --message <message> [--handles <handles>]
287
```
288

289
### Dashboard List Management CLI
290

291
Command-line tools for organizing dashboards into lists with item management.
292

293
```python { .api }
294
class DashboardListClient:  
295
    """CLI client for dashboard list management operations."""
296
    
297
    # Available commands:
298
    # dogshell dashboard_list show <list_id>
299
    # dogshell dashboard_list show_all
300
    # dogshell dashboard_list post --name <name> [options]
301
    # dogshell dashboard_list update <list_id> --name <name>
302
    # dogshell dashboard_list delete <list_id>
303
    # dogshell dashboard_list add_items <list_id> --dashboards <dashboard_ids>
304
    # dogshell dashboard_list update_items <list_id> --dashboards <dashboard_ids>
305
    # dogshell dashboard_list delete_items <list_id> --dashboards <dashboard_ids>
306
```
307

308
## Usage Examples
309

310
### Basic CLI Operations
311

312
```bash
313
# Configure authentication (one-time setup)
314
echo "[Connection]" > ~/.dogrc
315
echo "apikey = your-api-key" >> ~/.dogrc  
316
echo "appkey = your-app-key" >> ~/.dogrc
317

318
# Or use environment variables
319
export DATADOG_API_KEY=your-api-key
320
export DATADOG_APP_KEY=your-app-key
321

322
# Or pass keys as arguments
323
dogshell --api-key your-api-key --application-key your-app-key monitor show_all
324
```
325

326
### Monitor Management
327

328
```bash
329
# List all monitors
330
dogshell monitor show_all
331

332
# Show specific monitor
333
dogshell monitor show 12345
334

335
# Create a new monitor
336
dogshell monitor post \
337
  --type "metric alert" \
338
  --query "avg(last_5m):avg:system.cpu.user{*} > 80" \
339
  --name "High CPU usage" \
340
  --message "CPU usage is above 80% @webhook-http://example.com/hook"
341

342
# Update monitor
343
dogshell monitor update 12345 \
344
  --message "Updated alert message @slack-alerts"
345

346
# Mute monitor temporarily
347
dogshell monitor mute 12345 --end $(date -d "+1 hour" +%s)
348

349
# Search monitors
350
dogshell monitor search --query "cpu" --page 0 --per_page 10
351

352
# Delete monitor
353
dogshell monitor delete 12345
354
```
355

356
### Event Management
357

358
```bash
359
# Post an event
360
dogshell event post \
361
  --title "Deployment completed" \
362
  --text "Version 1.2.3 deployed to production" \
363
  --tags "version:1.2.3,env:production" \
364
  --alert_type "success"
365

366
# Query event stream
367
dogshell event stream \
368
  --start $(date -d "-1 hour" +%s) \
369
  --end $(date +%s) \
370
  --tags "env:production"
371

372
# Show specific event
373
dogshell event show 1234567890
374
```
375

376
### Metrics Operations
377

378
```bash
379
# Query metrics
380
dogshell metric query \
381
  --query "avg:system.cpu.user{*}" \
382
  --from $(date -d "-1 hour" +%s) \
383
  --to $(date +%s)
384

385
# Submit custom metric  
386
dogshell metric post \
387
  --metric "custom.business.metric" \
388
  --points "[[$(date +%s), 42.5]]" \
389
  --tags "service:web,env:production"
390

391
# List active metrics
392
dogshell metric list
393
```
394

395
### Infrastructure Management
396

397
```bash
398
# Search hosts
399
dogshell hosts search --filter "env:production"
400

401
# Show all hosts
402
dogshell hosts show_all
403

404
# Get host totals
405
dogshell hosts totals
406

407
# Mute host notifications
408
dogshell host mute web01.example.com \
409
  --end $(date -d "+2 hours" +%s) \
410
  --message "Maintenance window"
411

412
# Add tags to host
413
dogshell tag add web01.example.com role:webserver tier:frontend
414

415
# Show host tags
416
dogshell tag show web01.example.com
417

418
# Show all tags
419
dogshell tag show_all
420
```
421

422
### Dashboard Management
423

424
```bash
425
# Show dashboard
426
dogshell dashboard show abcd-1234-efgh-5678
427

428
# List all dashboards
429
dogshell dashboard show_all
430

431
# Create dashboard (requires complex JSON)
432
cat > dashboard.json << EOF
433
{
434
  "title": "My Dashboard",
435
  "layout_type": "ordered",
436
  "widgets": [
437
    {
438
      "definition": {
439
        "type": "timeseries",
440
        "requests": [{"q": "avg:system.cpu.user{*}"}],
441
        "title": "CPU Usage"
442
      }
443
    }
444
  ]
445
}
446
EOF
447

448
dogshell dashboard post \
449
  --title "My Dashboard" \
450
  --layout_type "ordered" \
451
  --widgets "$(cat dashboard.json | jq '.widgets')"
452
```
453

454
### Downtime Management
455

456
```bash
457
# Schedule downtime for maintenance
458
dogshell downtime post \
459
  --scope '["env:production", "service:web"]' \
460
  --start $(date -d "+10 minutes" +%s) \
461
  --end $(date -d "+2 hours" +%s) \
462
  --message "Scheduled maintenance window"
463

464
# Show all current downtimes
465
dogshell downtime show_all --current_only
466

467
# Cancel downtime
468
dogshell downtime cancel 98765
469
```
470

471
### Service Level Objectives
472

473
```bash
474
# Create SLO
475
dogshell service_level_objective post \
476
  --name "API Response Time SLO" \
477
  --type "metric" \
478
  --query '{"numerator": "sum:trace.web.request{service:api,resource_name:GET_/api/users}.ok", "denominator": "sum:trace.web.request{service:api,resource_name:GET_/api/users}"}' \
479
  --thresholds '[{"timeframe": "7d", "target": 99.9, "warning": 99.5}]' \
480
  --target_threshold 99.9 \
481
  --warning_threshold 99.5
482

483
# Show SLO history
484
dogshell service_level_objective history slo-abc-123 \
485
  --from $(date -d "-7 days" +%s) \
486
  --to $(date +%s)
487
```
488

489
### Advanced CLI Usage
490

491
```bash
492
# Use different output formats
493
dogshell monitor show_all --pretty   # Human-readable
494
dogshell monitor show_all --raw      # Raw JSON
495
dogshell monitor show_all            # Default format
496

497
# Use custom timeout
498
dogshell --timeout 30 monitor show_all
499

500
# Use different Datadog site
501
dogshell --api_host us5 monitor show_all  # US5 site
502
dogshell --api_host eu monitor show_all   # EU site
503

504
# Pipe output for processing
505
dogshell monitor show_all --raw | jq '.[] | select(.type == "metric alert")'
506

507
# Batch operations with shell scripting
508
for monitor_id in $(dogshell monitor show_all --raw | jq -r '.[].id'); do
509
  dogshell monitor mute $monitor_id --end $(date -d "+1 hour" +%s)
510
done
511
```
512

513
### Configuration Management
514

515
```bash
516
# Use custom config file
517
dogshell --config /path/to/custom.dogrc monitor show_all
518

519
# Override config with environment variables
520
DATADOG_API_KEY=override-key dogshell monitor show_all
521

522
# Override config with command line
523
dogshell --api-key override-key --application-key override-app-key monitor show_all
524
```
525

526
### Command Wrappers
527

528
```bash
529
# Wrap commands with metrics collection
530
dogwrap -n "backup.duration" -t "type:database" -- /usr/local/bin/backup-database.sh
531

532
# Wrap with custom tags and sample rate
533
dogwrap -n "deployment.time" -t "env:production,version:1.2.3" -s 1.0 -- ./deploy.sh
534

535
# Shell wrapper for multiple commands
536
dogshellwrap -n "batch.processing" -t "job:nightly" << 'EOF'
537
/usr/local/bin/process-data.sh
538
/usr/local/bin/generate-reports.sh  
539
/usr/local/bin/cleanup-temp-files.sh
540
EOF
541
```
542

543
### Error Handling and Debugging
544

545
```bash
546
# Enable verbose output (if available)
547
dogshell --timeout 60 monitor show_all
548

549
# Handle errors in scripts
550
if dogshell monitor show 12345 >/dev/null 2>&1; then
551
  echo "Monitor exists"
552
else
553
  echo "Monitor not found or error occurred"
554
fi
555

556
# Check exit codes
557
dogshell monitor show 12345
558
if [ $? -eq 0 ]; then
559
  echo "Command succeeded"
560
else
561
  echo "Command failed with exit code $?"
562
fi
563
```
564

565
## CLI Best Practices
566

567
### Authentication Security
568

569
```bash
570
# Good: Use config file with restricted permissions
571
chmod 600 ~/.dogrc
572

573
# Good: Use environment variables
574
export DATADOG_API_KEY=$(cat /secure/path/api-key)
575

576
# Avoid: Command line arguments (visible in process list)
577
# dogshell --api-key your-key-here  # Don't do this
578
```
579

580
### Automation and Scripting
581

582
```bash
583
#!/bin/bash
584
# Good: Robust error handling in automation scripts
585

586
set -euo pipefail  # Exit on error, undefined vars, pipe failures
587

588
# Function to check if monitor exists
589
check_monitor() {
590
  local monitor_id=$1
591
  if dogshell monitor show "$monitor_id" >/dev/null 2>&1; then
592
    return 0
593
  else
594
    return 1
595
  fi
596
}
597

598
# Create monitor only if it doesn't exist
599
if ! check_monitor 12345; then
600
  dogshell monitor post \
601
    --type "metric alert" \
602
    --query "avg(last_5m):avg:system.cpu.user{*} > 80" \
603
    --name "High CPU usage"
604
fi
605
```
606

607
### Output Processing
608

609
```bash
610
# Good: Use --raw for machine processing
611
dogshell monitor show_all --raw | jq '.[] | select(.name | contains("production"))'
612

613
# Good: Use --pretty for human consumption  
614
dogshell monitor show_all --pretty | grep -A5 -B5 "critical"
615

616
# Parse JSON safely
617
monitors=$(dogshell monitor show_all --raw)
618
echo "$monitors" | jq -r '.[] | "\(.id): \(.name)"'
619
```