Improve CLI help and human output UX#117
Conversation
Review carefully before merging. Consider a major version bump. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
This PR improves Fizzy's interactive CLI experience to feel more like a polished end-user tool. It reworks help output with guided sections and examples, improves human-facing output rendering with styled and markdown support, adds command aliases for common patterns, and enhances error presentation for interactive contexts.
Changes:
- New help system with command grouping, common workflows, examples, and aliases
- Improved output rendering with
StyledSummaryandMarkdownSummaryenhancements that include structured data - Refactored output functions (
printMutation,printDetail) for consistent format handling - Added breadcrumb navigation ("Next steps") for human output
- Added lightweight aliases (list→ls, show→view, delete→rm)
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| internal/render/render.go | Modified StyledSummary to include structured data below mutation summaries |
| internal/render/markdown.go | Modified MarkdownSummary to include structured data below mutation summaries |
| internal/render/render_test.go | Added test for StyledSummary with data inclusion |
| internal/render/markdown_test.go | Added test for MarkdownSummary with data inclusion |
| internal/commands/help.go | New file with comprehensive CLI help system implementation |
| internal/commands/help_test.go | New tests for help rendering |
| internal/commands/root.go | Major refactoring: added output formatting functions, error handling, human output helpers, and column inference |
| internal/commands/version.go | Updated to handle styled/markdown format output |
| internal/commands/auth.go | Changed to use printList with authProfileColumns |
| internal/commands/columns.go | Added authProfileColumns definition |
| internal/commands/column.go | Changed to use printDetail instead of printSuccess |
| internal/commands/skill.go | Changed to use printMutation for consistent output |
| internal/commands/signup.go | Changed to use printMutation and printDetail for consistent output |
| internal/commands/setup_agents.go | Changed to use printMutation and removed unused import |
| internal/commands/auth_test.go | Added comprehensive test for styled output with next steps |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (2)
internal/render/render.go:169
- StyledSummary will panic if data is nil because len() is called without a nil check. When toMap() returns nil (which it can when data cannot be converted to a map), calling len(data) on line 160 and 165 will panic. Add a nil check before calling len().
func StyledSummary(data map[string]any, summary string) string {
if summary != "" {
line := lipgloss.NewStyle().Bold(true).Render("✓ " + summary)
if len(data) == 0 {
return line + "\n"
}
return line + "\n\n" + StyledDetail(data, "")
}
if len(data) == 0 {
return lipgloss.NewStyle().Bold(true).Render("✓ Done") + "\n"
}
return StyledDetail(data, "")
}
internal/render/markdown.go:84
- MarkdownSummary will panic if data is nil because len() is called without a nil check. When toMap() returns nil (which it can when data cannot be converted to a map), calling len(data) on line 75 and 80 will panic. Add a nil check before calling len().
func MarkdownSummary(data map[string]any, summary string) string {
if summary != "" {
if len(data) == 0 {
return fmt.Sprintf("> %s\n", summary)
}
return fmt.Sprintf("> %s\n\n%s", summary, MarkdownDetail(data, ""))
}
if len(data) == 0 {
return "> Done\n"
}
return MarkdownDetail(data, "")
}
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Followed up on the suppressed nil-map note: no code change needed there because is safe in Go, so the current summary helpers already handle nil maps correctly. |
|
Follow-up correction: no code change needed for the nil-map note because calling len on a nil map is safe in Go, so the current summary helpers already handle nil maps correctly. |
- show root-local flags like --version in custom root help - use ExecuteC() so human usage errors know which command failed - suggest <failed command> --help instead of always fizzy --help - add regression tests for root help and usage hint behavior - regenerate SURFACE.txt for Cobra default version flag
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Summary
This improves Fizzy’s interactive CLI experience so it feels more like a polished end-user tool instead of an API wrapper. The main goal is to make the default human experience easier to learn, easier to navigate, and more consistent, especially when compared with CLIs like
gh.What changed
list→lsshow→viewdelete→rmNotes
Summary by cubic
Polished Fizzy’s interactive CLI help and human output for a guided, friendlier experience. Adds grouped help, smarter human printers (tables, summaries with data, next steps/location), clearer command‑specific error hints, and safer signup output in human modes.
New Features
--helpgroups commands (Core/Collaboration/Admin/Utilities), shows USAGE/ALIASES/SEE ALSO with colored EXAMPLES, splits “GLOBAL OUTPUT FLAGS” vs “GLOBAL CONFIG FLAGS”, and lists root‑local flags like--version. Subcommands get clearer usage, aliases (list→ls,show→view,delete→rm), examples, and see‑also.fizzy commandsrenders a styled catalog in human modes; use--jsonfor a structured catalog.auth listrenders a table with Profile/Active/Board/Base URL.versionprintsfizzy version <x>in human modes.fizzy <cmd> --helpfor usage.”).code,requires_signup_completion,account). JSON/quiet/agent modes keep full data.Refactors
configureCLIUXand custom human help;--agenthelp still supported.printList,printDetail,printMutation*) across commands; removed deprecated title‑casing for field names.Written for commit 799540b. Summary will update on new commits.