feat(cli): redesign help output with Devsy purple accent

[skevetter]

Summary

Replaces cobra's default --help with a renderer modeled applied across the whole command tree.

• New layout — uppercase section headers, a flat alphabetical SUBCOMMANDS list, and flags rendered above their wrapped descriptions instead of crammed into one column. The old single-column form got cramped on flag-heavy commands like devsy workspace up (~40 flags).
• Devsy purple accent (#7C5CFF, the desktop app's .theme-purple primary) on flag names and environment variables — the two things a reader scans for. Env vars moved from the usage string onto a pflag annotation so they can be styled independently.
• devsy self update → devsy update. The self parent held exactly one subcommand, so it added nesting without grouping anything.
• Dropped the redundant Devsy prefix from command descriptions ("Devsy Machine commands" → "Manage provider-hosted machines"). The binary name is already on every line being scanned.

USAGE:
devsy [global-flags] <subcommand>
SUBCOMMANDS:
machine Manage provider-hosted machines
update Update the CLI to the newest version
workspace Manage devcontainer workspaces
GLOBAL OPTIONS:
--context string, $DEVSY_CONTEXT <- flag bold purple, env var purple
The context to use

Breaking change

devsy self update is no longer recognized — use devsy update. No back-compat alias. The only in-repo caller was one e2e test, updated here; no docs, desktop, or scripts referenced the old path.

Notes for review

• Retired the cobra command groups. They existed solely to drive the old section headers, so leaving them would have been dead config. This collapsed registerSubcommands to a single AddCommand call and incidentally cleared a pre-existing funlen warning on it.
• colorprofile v0.4.3 gotcha — NewWriter(w, nil) documents a nil environ as meaning os.Environ(), but it builds an empty map, so TERM reads as unset and every profile collapses to NoTTY, silently stripping all color. pkg/clihelp/help.go passes os.Environ() explicitly with a comment, since reverting to nil looks harmless and isn't.
• theme.Accent is a single tone, not a lipgloss light/dark pair: resolving a pair needs terminal raw mode, too costly for a --help render. It clears 4.3:1 contrast on both black and white.

Verified on a real pty at root, group, and leaf level, plus the gated pro tree: color renders, NO_COLOR drops color while keeping bold, and piped output is plain. devsy update --dry-run exercised end-to-end. New tests in pkg/clihelp; touched packages lint clean.

Two pre-existing failures are unrelated and untouched: a podman test in pkg/compose and the e2e suite (needs Docker).

Summary by CodeRabbit

• New Features

  • Added redesigned CLI help with organized sections for subcommands, options, global options, defaults, and environment variables.
  • Added consistent command and option styling, with terminal-aware formatting.
  • Added the top-level update command.

• Changes

  • Updated command descriptions for clearer, more concise help output.
  • Replaced self update --dry-run with update --dry-run.
  • Environment variable names now appear clearly alongside related options.

[netlify]

✅ Deploy Preview for images-devsy-sh canceled.

Name	Link
🔨 Latest commit	1ddbad0
🔍 Latest deploy log	https://app.netlify.com/projects/images-devsy-sh/deploys/6a6999cfd5b6710008ce120e

[netlify]

✅ Deploy Preview for devsydev canceled.

Name	Link
🔨 Latest commit	1ddbad0
🔍 Latest deploy log	https://app.netlify.com/projects/devsydev/deploys/6a6999cfc928ab0008c12b08

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1c80e45d-8e94-4142-beb0-5c0c172e6cfc

📥 Commits

Reviewing files that changed from the base of the PR and between 4060061 and 1ddbad0.

📒 Files selected for processing (17)

• cmd/context/context.go
• cmd/env/env.go
• cmd/env_flags_test.go
• cmd/ide/ide.go
• cmd/machine/machine.go
• cmd/mcp/mcp.go
• cmd/provider/provider.go
• cmd/root.go
• cmd/secrets/secrets.go
• cmd/self/self.go
• cmd/update/update.go
• cmd/update/update_test.go
• e2e/tests/self/self.go
• pkg/clihelp/help.go
• pkg/clihelp/help_test.go
• pkg/flags/env.go
• pkg/theme/theme.go

💤 Files with no reviewable changes (1)

• cmd/self/self.go

---

📝 Walkthrough

Walkthrough

The CLI adds custom formatted help output with themed sections, environment-variable annotations, wrapping, filtering, and tests. Root command registration is simplified, update becomes a top-level command, self is removed, and command descriptions are revised.

Changes

CLI help and command restructuring

Layer / File(s)	Summary
Custom help rendering and metadata pkg/clihelp/*, pkg/theme/*, pkg/flags/env.go, cmd/env_flags_test.go	Custom help and usage rendering formats commands, flags, defaults, environment variables, wrapping, and terminal styling; environment bindings use annotations instead of modifying flag usage text; rendering behavior is tested.
Root registration and update command cmd/root.go, cmd/update/*, cmd/self/self.go, e2e/tests/self/self.go	Root help wiring and descriptions are added, command groups are removed, update is registered directly, the self command implementation is removed, and the e2e invocation uses update --dry-run.
Command descriptions cmd/context/context.go, cmd/env/env.go, cmd/ide/ide.go, cmd/machine/machine.go, cmd/mcp/mcp.go, cmd/provider/provider.go, cmd/secrets/secrets.go	Cobra short descriptions are updated for contexts, environment variables, IDE preferences, machines, MCP, providers, and secrets.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• devsy-org/devsy#219: Related to root command wiring and registration of additional commands.
• devsy-org/devsy#419: Related to the shared environment-variable binding and annotation contract.

Sequence Diagram(s)

sequenceDiagram
participant User
participant BuildRoot
participant Cobra
participant clihelp
User->>BuildRoot: request CLI help
BuildRoot->>Cobra: register commands and help handlers
Cobra->>clihelp: render command metadata and flags
clihelp-->>User: formatted help output

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 31.58% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: a CLI help output redesign with the Devsy purple accent.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}