Command-Line Tools

def main():
    """
    Main entry point for dogshell CLI commands.
    
    Available as console scripts:
    - dogshell: Primary CLI command
    - dog: Legacy CLI command (deprecated, use dogshell)
    - dogwrap: Command wrapper with metrics collection
    - dogshellwrap: Shell wrapper with metrics collection
    
    Global Options:
    - --config: Path to dogrc configuration file (default: ~/.dogrc)
    - --api-key: Datadog API key (or DATADOG_API_KEY env var)
    - --application-key: Datadog app key (or DATADOG_APP_KEY env var)
    - --pretty: Human-readable output formatting
    - --raw: Raw JSON output
    - --timeout: Request timeout in seconds (default: 10)
    - --api_host: Datadog site (us, eu, us3, us5, ap1, gov, or custom URL)
    """

# Configuration file format (~/.dogrc):
# [Connection]
# apikey = your-api-key
# appkey = your-app-key
# api_host = https://api.datadoghq.com

class MonitorClient:
    """CLI client for monitor management operations."""
    
    # Available commands:
    # dogshell monitor show <monitor_id>
    # dogshell monitor show_all [--group_states <states>] [--tags <tags>]
    # dogshell monitor post --type <type> --query <query> --name <name> [options]
    # dogshell monitor update <monitor_id> [options]
    # dogshell monitor delete <monitor_id> [--force]
    # dogshell monitor mute <monitor_id> [--scope <scope>] [--end <timestamp>]
    # dogshell monitor unmute <monitor_id> [--scope <scope>]
    # dogshell monitor mute_all
    # dogshell monitor unmute_all
    # dogshell monitor search [--query <query>] [--page <page>] [--per_page <count>]
    # dogshell monitor validate --type <type> --query <query>

class EventClient:
    """CLI client for event management operations."""
    
    # Available commands:
    # dogshell event post --title <title> --text <text> [options]
    # dogshell event show <event_id>
    # dogshell event stream [--start <timestamp>] [--end <timestamp>] [options]
    
    # Event post options:
    # --date_happened <timestamp>: When event occurred
    # --priority <normal|low>: Event priority
    # --tags <tag1,tag2>: Comma-separated tags
    # --alert_type <error|warning|info|success>: Alert type
    # --aggregation_key <key>: Aggregation key for grouping
    # --source_type_name <source>: Source type identifier
    # --host <hostname>: Host name for event

class MetricClient:
    """CLI client for metrics operations."""
    
    # Available commands:
    # dogshell metric query --query <query> --from <timestamp> --to <timestamp>
    # dogshell metric post --metric <name> --points <points> [options]
    # dogshell metric list
    
    # Metric post options:
    # --points: JSON array of [timestamp, value] pairs
    # --host <hostname>: Host name for metric
    # --tags <tag1,tag2>: Comma-separated tags
    # --type <gauge|count|rate>: Metric type
    # --interval <seconds>: Metric interval

class DashboardClient:
    """CLI client for dashboard management (v2 API)."""
    
    # Available commands:
    # dogshell dashboard show <dashboard_id>
    # dogshell dashboard show_all [--filter_shared] [--filter_deleted]
    # dogshell dashboard post --title <title> --widgets <widgets_json> --layout_type <type>
    # dogshell dashboard update <dashboard_id> [options]
    # dogshell dashboard delete <dashboard_id>

class TimeboardClient:
    """CLI client for timeboard management (v1 API, legacy)."""
    
    # Available commands:
    # dogshell timeboard show <timeboard_id>
    # dogshell timeboard show_all
    # dogshell timeboard post --title <title> --graphs <graphs_json>
    # dogshell timeboard update <timeboard_id> [options]
    # dogshell timeboard delete <timeboard_id>

class ScreenboardClient:
    """CLI client for screenboard management (v1 API, legacy)."""
    
    # Available commands:
    # dogshell screenboard show <screenboard_id>
    # dogshell screenboard show_all
    # dogshell screenboard post --board_title <title> --widgets <widgets_json>
    # dogshell screenboard update <screenboard_id> [options]
    # dogshell screenboard delete <screenboard_id>
    # dogshell screenboard share <screenboard_id>

class HostClient:
    """CLI client for individual host operations."""
    
    # Available commands:
    # dogshell host mute <hostname> [--end <timestamp>] [--message <message>] [--override]
    # dogshell host unmute <hostname>

class HostsClient:
    """CLI client for host management operations."""
    
    # Available commands:
    # dogshell hosts search [--filter <filter>] [--sort_field <field>] [--sort_dir <asc|desc>]
    # dogshell hosts show_all
    # dogshell hosts totals

class TagClient:
    """CLI client for tag management operations."""
    
    # Available commands:
    # dogshell tag show <hostname> [--source <source>]
    # dogshell tag add <hostname> <tag1> <tag2> ... [--source <source>]
    # dogshell tag replace <hostname> <tag1> <tag2> ... [--source <source>]
    # dogshell tag detach <hostname> [--source <source>]
    # dogshell tag show_all [--source <source>]

class DowntimeClient:
    """CLI client for downtime management operations."""
    
    # Available commands:
    # dogshell downtime show <downtime_id>
    # dogshell downtime show_all [--current_only]
    # dogshell downtime post --scope <scope> [options]
    # dogshell downtime update <downtime_id> [options]
    # dogshell downtime cancel <downtime_id>
    
    # Downtime post options:
    # --scope: JSON array of scope tags
    # --start <timestamp>: Start time (optional, defaults to now)
    # --end <timestamp>: End time (optional for indefinite)
    # --message <message>: Downtime message
    # --timezone <tz>: Timezone identifier
    # --recurrence <recurrence_json>: Recurrence configuration
    # --monitor_id <id>: Specific monitor to mute
    # --monitor_tags <tags>: Monitor tags to match

class ServiceLevelObjectiveClient:
    """CLI client for SLO management operations."""
    
    # Available commands:
    # dogshell service_level_objective show <slo_id>
    # dogshell service_level_objective show_all [options]
    # dogshell service_level_objective post --name <name> --type <type> --query <query> [options]
    # dogshell service_level_objective update <slo_id> [options]
    # dogshell service_level_objective delete <slo_id> [--force]
    # dogshell service_level_objective history <slo_id> --from <timestamp> --to <timestamp>
    
    # SLO post options:
    # --thresholds: JSON array of threshold configurations
    # --timeframe <7d|30d|90d>: Time window
    # --target_threshold <float>: Target percentage (0-100)
    # --warning_threshold <float>: Warning percentage
    # --description <text>: SLO description
    # --tags <tag1,tag2>: Comma-separated tags

class SearchClient:
    """CLI client for search operations across Datadog resources."""
    
    # Available commands:
    # dogshell search query <query_string> [--facets <facets>]
    # dogshell search metrics <query> [--limit <limit>]
    # dogshell search hosts <query> [--limit <limit>]
    # dogshell search tags <query> [--limit <limit>]

class ServiceCheckClient:
    """CLI client for service check operations."""
    
    # Available commands:
    # dogshell service_check check --check <name> --status <status> [options]
    
    # Service check options:
    # --status <0|1|2|3>: Check status (OK, WARNING, CRITICAL, UNKNOWN)
    # --timestamp <timestamp>: Check timestamp
    # --hostname <hostname>: Host name
    # --tags <tag1,tag2>: Comma-separated tags
    # --message <message>: Check message

class SecurityMonitoringClient:
    """CLI client for security monitoring operations."""
    
    # Available commands:
    # dogshell security_monitoring show <rule_id>
    # dogshell security_monitoring show_all
    # dogshell security_monitoring post --name <name> --queries <queries_json> [options]
    # dogshell security_monitoring update <rule_id> [options]  
    # dogshell security_monitoring delete <rule_id>
    # dogshell security_monitoring search_signals [options]

class CommentClient:
    """CLI client for comment management operations."""
    
    # Available commands:
    # dogshell comment show <comment_id>
    # dogshell comment post --message <message> [--handles <handles>]
    # dogshell comment update <comment_id> --message <message> [--handles <handles>]
    # dogshell comment reply <comment_id> --message <message> [--handles <handles>]

class DashboardListClient:  
    """CLI client for dashboard list management operations."""
    
    # Available commands:
    # dogshell dashboard_list show <list_id>
    # dogshell dashboard_list show_all
    # dogshell dashboard_list post --name <name> [options]
    # dogshell dashboard_list update <list_id> --name <name>
    # dogshell dashboard_list delete <list_id>
    # dogshell dashboard_list add_items <list_id> --dashboards <dashboard_ids>
    # dogshell dashboard_list update_items <list_id> --dashboards <dashboard_ids>
    # dogshell dashboard_list delete_items <list_id> --dashboards <dashboard_ids>

# Configure authentication (one-time setup)
echo "[Connection]" > ~/.dogrc
echo "apikey = your-api-key" >> ~/.dogrc  
echo "appkey = your-app-key" >> ~/.dogrc

# Or use environment variables
export DATADOG_API_KEY=your-api-key
export DATADOG_APP_KEY=your-app-key

# Or pass keys as arguments
dogshell --api-key your-api-key --application-key your-app-key monitor show_all

# List all monitors
dogshell monitor show_all

# Show specific monitor
dogshell monitor show 12345

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

# Update monitor
dogshell monitor update 12345 \
  --message "Updated alert message @slack-alerts"

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

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

# Delete monitor
dogshell monitor delete 12345

# Post an event
dogshell event post \
  --title "Deployment completed" \
  --text "Version 1.2.3 deployed to production" \
  --tags "version:1.2.3,env:production" \
  --alert_type "success"

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

# Show specific event
dogshell event show 1234567890

# Query metrics
dogshell metric query \
  --query "avg:system.cpu.user{*}" \
  --from $(date -d "-1 hour" +%s) \
  --to $(date +%s)

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

# List active metrics
dogshell metric list

# Search hosts
dogshell hosts search --filter "env:production"

# Show all hosts
dogshell hosts show_all

# Get host totals
dogshell hosts totals

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

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

# Show host tags
dogshell tag show web01.example.com

# Show all tags
dogshell tag show_all

# Show dashboard
dogshell dashboard show abcd-1234-efgh-5678

# List all dashboards
dogshell dashboard show_all

# Create dashboard (requires complex JSON)
cat > dashboard.json << EOF
{
  "title": "My Dashboard",
  "layout_type": "ordered",
  "widgets": [
    {
      "definition": {
        "type": "timeseries",
        "requests": [{"q": "avg:system.cpu.user{*}"}],
        "title": "CPU Usage"
      }
    }
  ]
}
EOF

dogshell dashboard post \
  --title "My Dashboard" \
  --layout_type "ordered" \
  --widgets "$(cat dashboard.json | jq '.widgets')"

# Schedule downtime for maintenance
dogshell downtime post \
  --scope '["env:production", "service:web"]' \
  --start $(date -d "+10 minutes" +%s) \
  --end $(date -d "+2 hours" +%s) \
  --message "Scheduled maintenance window"

# Show all current downtimes
dogshell downtime show_all --current_only

# Cancel downtime
dogshell downtime cancel 98765

# Create SLO
dogshell service_level_objective post \
  --name "API Response Time SLO" \
  --type "metric" \
  --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}"}' \
  --thresholds '[{"timeframe": "7d", "target": 99.9, "warning": 99.5}]' \
  --target_threshold 99.9 \
  --warning_threshold 99.5

# Show SLO history
dogshell service_level_objective history slo-abc-123 \
  --from $(date -d "-7 days" +%s) \
  --to $(date +%s)

# Use different output formats
dogshell monitor show_all --pretty   # Human-readable
dogshell monitor show_all --raw      # Raw JSON
dogshell monitor show_all            # Default format

# Use custom timeout
dogshell --timeout 30 monitor show_all

# Use different Datadog site
dogshell --api_host us5 monitor show_all  # US5 site
dogshell --api_host eu monitor show_all   # EU site

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

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

# Use custom config file
dogshell --config /path/to/custom.dogrc monitor show_all

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

# Override config with command line
dogshell --api-key override-key --application-key override-app-key monitor show_all

# Wrap commands with metrics collection
dogwrap -n "backup.duration" -t "type:database" -- /usr/local/bin/backup-database.sh

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

# Shell wrapper for multiple commands
dogshellwrap -n "batch.processing" -t "job:nightly" << 'EOF'
/usr/local/bin/process-data.sh
/usr/local/bin/generate-reports.sh  
/usr/local/bin/cleanup-temp-files.sh
EOF

# Enable verbose output (if available)
dogshell --timeout 60 monitor show_all

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

# Check exit codes
dogshell monitor show 12345
if [ $? -eq 0 ]; then
  echo "Command succeeded"
else
  echo "Command failed with exit code $?"
fi

# Good: Use config file with restricted permissions
chmod 600 ~/.dogrc

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

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

#!/bin/bash
# Good: Robust error handling in automation scripts

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

# Function to check if monitor exists
check_monitor() {
  local monitor_id=$1
  if dogshell monitor show "$monitor_id" >/dev/null 2>&1; then
    return 0
  else
    return 1
  fi
}

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

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

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

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