Task: Enhance CLI user experience with formatted output, examples, and smart defaults

[Ulrond]

Description

Improve xts CLI tool user experience to make it dead simple for everyone to use with no manual required. Focus on self-documenting commands, beautiful output formatting, and intelligent defaults.

Goals:

• Zero learning curve - commands should be self-explanatory
• Beautiful, informative output - not raw JSON dumps
• Smart defaults - minimize required parameters
• Helpful error messages with actionable suggestions
• Examples displayed in help for every command

Current Pain Points

1. Raw JSON Output - Unformatted curl responses are hard to read
2. No Examples - Users don't know command syntax without docs
3. Silent Failures - Errors don't explain what went wrong or how to fix
4. No Discovery - Can't explore what's available before committing
5. Verbose Syntax - Every parameter required even when defaults make sense

Proposed Enhancements

1. Formatted Output (Priority: HIGH)

Current:

{"slots": [{"id": 1, "state": "free", "platform": "alpha.uk"}]}

Proposed:

╭─────┬──────────┬─────────┬──────────┬─────────╮
│ ID  │ Platform │ State   │ Owner    │ Rack    │
├─────┼──────────┼─────────┼──────────┼─────────┤
│ 1   │ alpha.uk │ ✓ free  │ -        │ rack-a  │
│ 2   │ beta.us  │ ⚠ busy  │ -        │ rack-a  │
│ 5   │ alpha.uk │ ✗ alloc │ user@..  │ rack-b  │
╰─────┴──────────┴─────────┴──────────┴─────────╯

Implementation:

• Add response parsers for common JSON structures
• Use rich library for tables and formatting
• Color-code states (green=free, yellow=busy, red=allocated)
• Human-readable timestamps ("2h ago" vs ISO format)

2. Inline Examples (Priority: HIGH)

Make --help show actual examples:

$ xts allocator allocate by_id --help

Usage: xts allocator allocate by_id <email> <device_id> <duration>

Allocate a specific device by ID

Examples:
  # Allocate device 5 for 2 hours
  xts allocator allocate by_id user@example.com 5 2h
  
  # Allocate device 1 for 30 minutes
  xts allocator allocate by_id test@dev.com 1 30m

Arguments:
  email       Your email address for ownership tracking
  device_id   Numeric ID of device to allocate
  duration    How long to hold (30m, 2h, or plain minutes)

Note: Already implemented in .xts files (rdkcentral/xts_allocator_server#28), needs xts_core to display them properly.

3. Smart Defaults & Shortcuts (Priority: MEDIUM)

# Auto-detect email from environment
export XTS_USER_EMAIL=user@example.com
xts allocator allocate by_id 5 2h  # Email implied

# Default duration if omitted
xts allocator allocate by_id user@example.com 5  # Defaults to 1h

# Shorter aliases
xts alloc 5 2h          # Short form
xts free 5              # Deallocate shortcut
xts mine                # Show my allocations

4. Better Error Messages (Priority: HIGH)

Current:

{"error": "Device not found"}

Proposed:

❌ Error: Device #5 not found

Available devices: 1, 2, 3, 4, 6-10

Suggestions:
  • List free devices:  xts allocator list free
  • Search by platform: xts allocator search by_platform alpha.uk
  • View all devices:   xts allocator list devices

Implementation:

• Parse error responses
• Add context-aware suggestions
• Show related commands
• Include quick fixes

5. Discovery Commands (Priority: MEDIUM)

Add convenience commands for exploration:

xts allocator info        # Server status, available platforms, counts
xts allocator whoami      # My current allocations
xts allocator platforms   # List all platforms with free/total counts
xts allocator popular     # Most-used platforms

6. Interactive Mode (Priority: LOW)

$ xts allocator interactive

XTS Allocator Interactive Mode

→ Select action:
  1. Allocate device
  2. List devices
  3. Search devices
  4. My allocations
  
Enter number [1-4]: 1

→ Select server:
  1. lab-a (15 free)
  2. lab-b (8 free)
  3. localhost (3 free)
  
Enter number [1-3]: 1

→ Allocate by:
  1. Device ID
  2. Platform
  3. Tags
  
...

7. Progress Indicators (Priority: LOW)

$ xts allocator list devices --from-all

⠋ Querying servers: lab-a, lab-b, localhost...
✓ lab-a:     15 devices found
✓ lab-b:     8 devices found  
✗ localhost: Connection timeout (skipped)

Results from 2 servers:
[table with tagged origins]

Implementation Notes

• Use rich library (already a dependency) for formatting
• Add response parser layer in xts.py
• Maintain backward compatibility - add --json flag for raw output
• Examples from .xts files should render in help
• Consider XTS_OUTPUT_FORMAT env var (table/json/compact)

Acceptance Criteria

• JSON responses formatted as readable tables
• Color-coded output based on state/status
• Examples shown in --help for all commands
• Error messages include suggestions
• At least 3 smart defaults implemented
• --json flag preserves raw output for scripting

Related Work

• xts_allocator_server .xts file already has comprehensive examples
• Coordinates with issue Task: Add XTS CLI integration for centrally-managed device allocation commands #59 (namespace handling)
• Would benefit federated server queries (Task: Add XTS CLI integration for centrally-managed device allocation commands #59 comment)