Task: Improve CLI output formatting and command discovery UX

[Ulrond]

Description

Enhance xts_core CLI user experience by improving output formatting and command discovery. Currently, commands dump raw JSON/text output and help text is minimal, making the tool harder to use.

Goals:

• Format JSON responses as readable tables
• Improve help text with examples and usage patterns
• Better command discovery and navigation
• Clear, actionable error messages

Current Issues

Output Formatting:

• Raw JSON dumps from curl commands are hard to read
• No visual formatting (colors, tables, alignment)
• Large outputs are overwhelming
• Status information not human-readable

Help/Discovery:

• Generic help text without examples
• Hard to discover available commands from aliased .xts files
• No guidance on command syntax or parameters
• Error messages lack context and suggestions

Proposed Solutions

1. Output Formatting

• Detect JSON responses and format as tables using rich library
• Color-code important information (states, errors, warnings)
• Align columns for readability
• Support --format flag: json, table, csv
• Truncate long outputs with pagination or summary view

2. Help/Discovery Improvements

• Add examples to all command help text
• Show command structure visually (tree format)
• Include parameter descriptions and types
• Add --examples flag to show usage patterns
• Better error messages with suggestions:

  Current: "Command not found"
  Better:  "Command 'allocat' not found. Did you mean 'allocate'?"
  

Implementation Notes

• Use existing rich library already in dependencies
• Parse curl command output before displaying
• Add formatting layer in yaml_runner or xts.py
• Extend argparse help formatters for better examples
• Consider adding command completion support

Benefits

• Faster comprehension of command output
• Reduced learning curve for new users
• Better discoverability of available commands
• Professional, polished CLI experience
• Fewer support questions about usage