enhancement: bgctl CLI usability improvements (error messages, help text, flags)

[MaxRink]

Summary

Multiple CLI usability improvements identified across the bgctl command-line tool.

Items

1. Error messages lack actionable suggestions

Files: pkg/bgctl/cmd/debug.go:105, pkg/bgctl/cmd/escalation.go:49, pkg/bgctl/cmd/session.go:199

Invalid output format returns "unknown output format: X" without listing available options. Similarly, config.go:395 returns "context not found: X" without suggesting bgctl config get-contexts.

Fix: Include available options in error messages:

return fmt.Errorf("unknown output format: %s (choose from: table, json, yaml, wide)", format)

2. Missing Long help text and examples

Files: Most commands in pkg/bgctl/cmd/

Only debug session create has a Long description with examples. Commands like session request, session approve, escalation list lack usage examples.

Fix: Add Long descriptions with examples to all commands.

3. Vague flag descriptions

File: pkg/bgctl/cmd/session.go:204, pkg/bgctl/cmd/debug.go:114

• --state "Filter by state" - does not mention comma-separated format
• --interval "Polling interval" - does not mention duration format (e.g., 2s, 1m)

Fix: Include expected format in flag descriptions.

4. No progress indicator for bgctl update

File: pkg/bgctl/cmd/update.go:115-140

Downloads and installs a new binary with no progress feedback. Appears hung during 30+ second downloads.

Fix: Add progress output: fmt.Fprintf(os.Stderr, "Downloading %s...\n", assetName)

5. Missing common short flags

File: pkg/bgctl/cmd/root.go:104-111, pkg/bgctl/cmd/session.go:201-210

Frequently used flags like --cluster, --user, --group, --reason, --duration lack short forms.

Review Persona

CLI Usability