enhancement: phase 2 roadmap — improve CLI ergonomics with shared conventions, doctor, output modes, and generated docs

[electather]

Problem / motivation

The CLI has grown into a broad command surface, but it would benefit from more consistent UX and better operator tooling.

Current opportunities include:

• command convention inconsistencies across subcommands
• missing validation and shared flag patterns
• no dedicated doctor command for config/connectivity checks
• JSON-first output with limited human-friendly options
• docs likely to drift as commands evolve

Proposed solution

Improve CLI ergonomics and maintainability in one coordinated phase.

Scope:

• standardise command conventions and validation patterns
• add a doctor command
• add output modes such as json, yaml, and table
• generate CLI command reference documentation from Cobra metadata

Alternatives considered

Treat each improvement as separate work. That is possible, but the pieces are closely related and benefit from a shared design pass.

Additional context

Related existing issue:

• refactor: Migrate cmd/users/ to use shared apiutil.HandleResponse helper

Suggested checklist:

• Define command UX conventions
• Introduce shared validation/helpers where appropriate
• Implement seerr-cli doctor
• Add configurable output modes
• Generate CLI reference docs