feat(cli): add comprehensive help system and fix ISO8601 confusion

[tmcinerney]

Summary

This PR significantly enhances the CLI help system to make ddog fully self-discoverable, fixing a critical issue where metrics commands incorrectly showed ISO8601 support in help output despite not actually supporting it. All commands now provide comprehensive inline documentation with query syntax examples, time format guidance, and usage patterns.

Problem

1. Critical Issue: Metrics commands showed ISO8601 timestamp support in help but the parsing code explicitly rejects it, causing user confusion and errors
2. Insufficient Help: Running ddog --help or command-specific help provided minimal guidance
3. Missing Context: No information about:
   • Required environment variables
   • Query syntax patterns for each domain (logs, spans, metrics)
   • Output format (NDJSON)
   • Time format limitations and units
   • Links to official Datadog documentation

This made it difficult for both humans and LLMs to use the tool effectively without consulting external documentation.

Solution

Core Changes

1. Fixed ISO8601 Confusion (src/cli/shared.rs)

• Created separate TimeRangeRelativeOnly struct for metrics commands
• Added explicit warnings that ISO8601 is NOT supported
• Updated metrics commands to use the new struct
• Prevents users from attempting to use unsupported formats

2. Comprehensive Help Text
Added detailed long_help attributes throughout:

• Main CLI (src/cli/args.rs): Environment variables, output format, examples
• Logs (src/cli/logs.rs): Query syntax with attributes, tags, ranges, boolean operators
• Spans (src/cli/spans.rs): APM-specific syntax with duration queries, resource filtering
• Metrics (src/cli/metrics.rs): Aggregations, tag filtering, arithmetic, functions

Each command includes:

• Query syntax patterns with concrete examples
• Output format explanation
• Common use cases with jq integration
• Links to Datadog documentation

3. Enhanced README (README.md)

• Added Quick Start section
• Added pre-built binary download instructions
• Documented cargo install/uninstall methods
• Created Common Options section consolidating time format documentation
• Moved Output Format section higher for visibility
• Eliminated ~50 lines of duplicated documentation

Impact

For Users

• No more ISO8601 confusion: Clear warnings prevent attempting unsupported formats with metrics
• Self-documenting: ddog --help and ddog <command> <action> --help provide complete usage guidance
• Faster onboarding: Query syntax examples make it easy to construct valid queries
• Better discovery: Environment variables and output format documented inline

For LLMs

• Complete context: All information needed to construct commands available via --help
• Reduced errors: Type-safe separation of time format structs prevents invalid combinations
• Clear examples: Concrete query patterns for each domain reduce trial-and-error

Code Quality

• Type safety: Separate structs enforce different constraints at compile time
• DRY README: Consolidated common options eliminate duplication
• Better organization: Help text co-located with command definitions

Examples

Before

$ ddog metrics query --help
Query metrics timeseries data

Usage: ddog metrics query [OPTIONS] <QUERY>

Arguments:
  <QUERY>  Datadog metric query (e.g., "avg:system.cpu.user{*}")

Options:
  -f, --from <TIME>   Start time - relative (now-1h), ISO8601 (2024-01-15T10:00:00Z), or Unix ms
  -t, --to <TIME>     End time - relative (now), ISO8601 (2024-01-15T10:00:00Z), or Unix ms
  -l, --limit <N>     Maximum number of data points to return (use 0 for unlimited)

After

$ ddog metrics query --help
Query metrics timeseries data using Datadog's metric query syntax.

⚠️  Time Format Limitation:
  Metrics queries do NOT support ISO8601 timestamps.
  Use relative times (now-1h) or Unix timestamps only.

Query Syntax:
  • Basic: avg:system.cpu.user{*}
  • Aggregation: sum, avg, min, max, count
  • Tag filtering: avg:system.cpu.user{env:prod}
  • Multiple tags: avg:system.cpu.user{env:prod,service:web}
  • Wildcards: avg:system.cpu.user{host:web-*}
  • Arithmetic: avg:system.cpu.user{*} + avg:system.cpu.system{*}
  • Functions: avg:system.cpu.user{*}.rollup(avg, 60)

Output Format:
  Each line contains a JSON object with timestamp and metric value.
  Pipe to jq for processing: ddog metrics query "..." | jq '.value'

Examples:
  # Query CPU usage
  ddog metrics query "avg:system.cpu.user{*}" --from now-1h

  # Query with host filter
  ddog metrics query "max:system.mem.used{host:prod-*}"

  # With arithmetic
  ddog metrics query "avg:system.cpu.user{*} + avg:system.cpu.system{*}"

Documentation:
  https://docs.datadoghq.com/dashboards/querying/

[... argument details with examples ...]

Testing

• All existing tests pass
• Build successful with no warnings
• Help output verified for all commands

Files Changed

• src/cli/shared.rs (+110): New TimeRangeRelativeOnly struct
• src/cli/metrics.rs (+103): Comprehensive help for metrics commands
• README.md (+155, -50): Better structure, consolidated docs
• src/cli/logs.rs (+58): Query syntax documentation
• src/cli/spans.rs (+50): APM query syntax documentation
• src/cli/args.rs (+25): Environment variables and examples
• src/commands/metrics/*.rs (+8): Use new time range struct
• src/cli/mod.rs (+2): Export new type

Total: 9 files, 461 insertions(+), 50 deletions(-)

Documentation

The CLI is now fully self-documenting. Users and LLMs can discover:

• Required environment variables via ddog --help
• Query syntax for each domain via ddog <domain> <action> --help
• Time format options with clear limitations
• Output format and piping examples
• Links to official Datadog documentation for deep dives

🤖 Generated with Claude Code