feat(cli): redesign help output with Devsy purple accent by skevetter · Pull Request #806 · devsy-org/devsy

skevetter · 2026-07-29T04:48:33Z

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.

Replace cobra's default help with a renderer that reads top-down: uppercase section headers, grouped subcommand listings, and flags shown above their wrapped descriptions rather than crammed into a single column. Flag names and environment variables carry the Devsy purple accent so the two things a reader scans for stand out. This moves the env var out of the usage string and onto a pflag annotation, letting it be styled independently of the description text.

List every subcommand in one alphabetical SUBCOMMANDS section. At 14 top-level commands the grouped variant spent four headers and three blank lines on a list that fits on one screen either way. This retires the cobra command groups, which existed only to drive those headers, collapsing registerSubcommands to a single AddCommand call. Also rewrite the "Devsy X commands" descriptions as verb phrases. The binary name is already on every line the reader is scanning, so the prefix crowded out the part that distinguishes one command from another.

The `self` parent held exactly one subcommand, so it added a level of nesting without grouping anything. Moving update to the top level makes it reachable as `devsy update`. BREAKING CHANGE: `devsy self update` is no longer recognized. Use `devsy update`.

Drop the doc comments that restated their own function names and the per-style comments in theme, keeping only the ones a reader can't recover from the code: the colorprofile nil-environ bug, why Accent is a single tone, and why persistent flags count as global. Help output is byte-identical.

netlify · 2026-07-29T04:48:38Z

✅ 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 · 2026-07-29T04:48:41Z

✅ Deploy Preview for devsydev canceled.

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

coderabbitai · 2026-07-29T04:48:42Z

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

🚥 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

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

skevetter added 4 commits July 28, 2026 23:21

github-actions Bot added the size/xl label Jul 29, 2026

style: update comments

5afa000

skevetter marked this pull request as ready for review July 29, 2026 06:10

skevetter marked this pull request as draft July 29, 2026 06:12

Merge branch 'main' into feat/cli-help-theme

1ddbad0

skevetter marked this pull request as ready for review July 29, 2026 06:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

feat(cli): redesign help output with Devsy purple accent#806
skevetter wants to merge 6 commits into
mainfrom
feat/cli-help-theme

skevetter commented Jul 29, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

netlify Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 29, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

skevetter commented Jul 29, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking change

Notes for review

Summary by CodeRabbit

Uh oh!

netlify Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for images-devsy-sh canceled.

Uh oh!

netlify Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for devsydev canceled.

Uh oh!

coderabbitai Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

skevetter commented Jul 29, 2026 •

edited by coderabbitai Bot

Loading

netlify Bot commented Jul 29, 2026 •

edited

Loading

netlify Bot commented Jul 29, 2026 •

edited

Loading

coderabbitai Bot commented Jul 29, 2026 •

edited

Loading