Restructure CLI Help Output with Improved Categorization by cloin · Pull Request #265 · brevdev/brev-cli

cloin · 2025-10-31T18:08:55Z

Reorganizes the CLI help text into clearer, more intuitive semantic categories to improve command discoverability and user experience.

No breaking changes - All commands, flags, and functionality remain unchanged
Help text only - Changes are purely cosmetic to improve UX
Better discoverability - Users can more easily find relevant commands

Fix duplicate start command registration bug
Hide the secret, ollama and status commands because they don't work
Add "hidden" command annotation to hide fu and env-vars commands
Reorganize commands into semantic categories:
- Workspace Commands: core workspace operations (create, start, stop, ls, etc.)
- Workspace Access: tools for accessing workspaces (shell, open, copy, port-forward)
- Organization Management: org-related commands with org subcommands
- Configuration: settings, secrets, and account management
Update command annotations from old categories (context, ssh, housekeeping) to new ones
Add inline tips and hints to guide users (e.g., 'Use brev org --help for subcommands')
Improve help text discoverability by showing common org subcommands in main help

Before:

❯ brev --help

      brev client for managing instances

      Find more information at:
            https://brev.dev

Usage:
  brev [flags]
  brev [command]

Instance Commands:
  background             Run a command in the background with optional 'brev stop self' at the end
  create                 Create a new instance
  delete                 Delete a Brev instance
  reset                  Reset an instance if it's in a weird state.
  start                  Start an instance if it's stopped, or create one from url
  start                  Start an instance if it's stopped, or create one from url
  status                 About this instance
  stop                   Stop an instance if it's running

Context Commands:
  ls                     List instances within active org
  org                    Organization commands
  set                    Set active org (helps with completion)

SSH Commands:
  copy                   copy files and directories between local and remote instance
  open                   [beta] open VSCode, Cursor, Windsurf, or tmux to your instance
  port-forward           Enable a local tunnel
  shell                  [beta] open a shell in your instance

Quickstart Commands:
  ollama                 Start an Ollama model server

Housekeeping Commands:
  configure-env-vars     configure env vars in supported shells
  healthcheck            Check backend to see if it's healthy
  hello                  Get a quick onboarding of the Brev CLI
  import-ide-config      Import your IDE config
  invite                 Generate an invite link
  login                  Log into brev
  logout                 Log out of brev
  profile                Personal profile commands
  refresh                Force a refresh to the ssh config
  run-tasks              Run background tasks for brev
  secret                 Add a secret/environment variable
  ssh-key                Get your pulic SSH-Key

Flags:
  -h, --help              help for brev
      --no-check-latest   Do not check for the latest version when printing version
      --user string       non root user to use for per user configuration of commands run as root
      --version           Print version output

Use "brev [command] --help" for more information about a command.

After:

❯ ./brev -h

      brev client for managing instances

      Find more information at:
            https://brev.nvidia.com

Usage:
  brev [flags]
  brev [command]

Instance Commands:
  create                 Create a new instance
  delete                 Delete an instance
  ls                     List instances within active org

  The following commands have provider-dependent support:
  reset                  Reset an instance to recover from errors
  start                  Start an instance if it's stopped, or create one from url
  stop                   Stop an instance if it's running

Instance Access:
  copy                   Copy files and directories between local and remote instance
  open                   [beta] Open VSCode, Cursor, Windsurf, or tmux to your instance
  port-forward           Forward a port from instance to local machine
  shell                  [beta] Open a shell in your instance

Organization Management:
  invite                 Generate an invite link (alias for 'brev org invite')
  org                    Organization commands (run 'brev org --help' for subcommands)
  redeem                 Redeem a code for credits
  set                    Set active org (alias for 'brev org set')

Configuration:
  healthcheck            Check backend to see if it's healthy
  hello                  Get a quick onboarding of the Brev CLI
  login                  Log into Brev
  logout                 Log out of Brev
  profile                Personal profile commands
  refresh                Force a refresh to the SSH config
  ssh-key                Get your public SSH-Key

Flags:
  -h, --help              Help for Brev
      --no-check-latest   Do not check for the latest version when printing version
      --user string       Non root user to use for per user configuration of commands run as root
      --version           Print version output

Use "brev [command] --help" for more information about a command.

cloin · 2025-10-31T18:14:11Z

I don't think brev ollama works. Maybe we should remove it:

❯ ./brev ollama -h
Start an Ollama server with specified model types

Usage:
  brev ollama

Examples:

  brev ollama --model llama3


Flags:
  -g, --gpu string     GPU instance type. See https://brev.dev/docs/reference/gpu for details (default "g5.xlarge")
  -h, --help           help for ollama
  -m, --model string   AI/ML model type (e.g., llama2, llama3, mistral7b)

Global Flags:
      --no-check-latest   Do not check for the latest version when printing version
      --user string       non root user to use for per user configuration of commands run as root
      --version           Print version output

test

❯ ./brev ollama -m llama3
🤙🦙🤙🦙🤙🦙🤙



Creating Ollama server ollama-08ae3e13-0483-4b12-963a-232f56b1340a with model llama3 in org org-34ptcG5B1OI4G8HqwFota449NWO
⣻ Creating your workspace. Hang tight 🤙 [error]
github.com/brevdev/brev-cli/pkg/cmd/ollama.NewCmdOllama.func1
/Users/cmcnaughton/projects/brev/brev-cli/pkg/cmd/ollama/ollama.go:122
: [error]
github.com/brevdev/brev-cli/pkg/cmd/ollama.NewCmdOllama.func1.1
/Users/cmcnaughton/projects/brev/brev-cli/pkg/cmd/ollama/ollama.go:111
: [error]
github.com/brevdev/brev-cli/pkg/cmd/ollama.runOllamaWorkspace
/Users/cmcnaughton/projects/brev/brev-cli/pkg/cmd/ollama/ollama.go:172
: [error]
github.com/brevdev/brev-cli/pkg/cmd/ollama.runOllamaWorkspace.func1
/Users/cmcnaughton/projects/brev/brev-cli/pkg/cmd/ollama/ollama.go:162
: rpc error: code = NotFound desc = instance type g5.xlarge not found

kjw3 · 2025-10-31T18:15:25Z

I don't think brev ollama works. Maybe we should remove it:

❯ ./brev ollama -h
Start an Ollama server with specified model types

Usage:
  brev ollama

Examples:

  brev ollama --model llama3


Flags:
  -g, --gpu string     GPU instance type. See https://brev.dev/docs/reference/gpu for details (default "g5.xlarge")
  -h, --help           help for ollama
  -m, --model string   AI/ML model type (e.g., llama2, llama3, mistral7b)

Global Flags:
      --no-check-latest   Do not check for the latest version when printing version
      --user string       non root user to use for per user configuration of commands run as root
      --version           Print version output

test

❯ ./brev ollama -m llama3
🤙🦙🤙🦙🤙🦙🤙



Creating Ollama server ollama-08ae3e13-0483-4b12-963a-232f56b1340a with model llama3 in org org-34ptcG5B1OI4G8HqwFota449NWO
⣻ Creating your workspace. Hang tight 🤙 [error]
github.com/brevdev/brev-cli/pkg/cmd/ollama.NewCmdOllama.func1
/Users/cmcnaughton/projects/brev/brev-cli/pkg/cmd/ollama/ollama.go:122
: [error]
github.com/brevdev/brev-cli/pkg/cmd/ollama.NewCmdOllama.func1.1
/Users/cmcnaughton/projects/brev/brev-cli/pkg/cmd/ollama/ollama.go:111
: [error]
github.com/brevdev/brev-cli/pkg/cmd/ollama.runOllamaWorkspace
/Users/cmcnaughton/projects/brev/brev-cli/pkg/cmd/ollama/ollama.go:172
: [error]
github.com/brevdev/brev-cli/pkg/cmd/ollama.runOllamaWorkspace.func1
/Users/cmcnaughton/projects/brev/brev-cli/pkg/cmd/ollama/ollama.go:162
: rpc error: code = NotFound desc = instance type g5.xlarge not found

I agree. This is broken and we should remove or hide for now, until we decide if we want to fix and bring it back.

kjw3 · 2025-10-31T18:15:49Z

Overall these seem very intuitive and good cleanliness changes to me

theFong · 2025-10-31T23:16:49Z

Awesome thanks for taking a pass at cleaning stuff up! Should we also hide

import-ide-config
configure-env-vars
run-tasks
import-ide-config

can we rename "workspace" -> "instance" to match naming on console?

- Fix duplicate start command registration bug - Reorganize commands into semantic categories: - Workspace Commands: core workspace operations (create, start, stop, ls, etc.) - Workspace Access: tools for accessing workspaces (shell, open, copy, port-forward) - Organization Management: org-related commands with helpful subcommand hints - Configuration: settings, secrets, and account management - Quick Start: onboarding commands like ollama - Update command annotations from old categories (context, ssh, housekeeping) to new ones - Add inline tips and hints to guide users (e.g., 'Use brev org --help for subcommands') - Improve help text discoverability by showing common org subcommands in main help

- Move 'fu' command to hidden annotation (inappropriate name, dev-only) - Move 'env-vars' to hidden annotation (redundant with configure-env-vars) - These commands remain functional but won't appear in help text

- Move 'secret' command to hidden annotation (non-functional) - Command remains available but won't appear in help text

- Move 'ollama' command to hidden annotation (non-functional) - Removes 'Quick Start' section from help (no longer needed) - Command remains available but won't appear in help text

- Fix typo: 'pulic' -> 'public' in ssh-key description - Standardize capitalization: all descriptions start with capital letter - Capitalize proper nouns: Brev, SSH, CLI - Improve command descriptions for clarity - Remove misplaced org tip from workspace commands section - Remove detailed subcommand list from org help - Add inline tip to org command description

- Set org command to use default Cobra template instead of custom filtered template - Update annotations for org subcommands to use consistent 'orgsubcommand' annotation - This ensures all org subcommands (create, invite, ls, set) are visible when running 'brev org -h'

- Update Short descriptions to indicate they are aliases for 'brev org invite' and 'brev org set' - This makes it clearer to users that these are convenience shortcuts

- Capitalize first letter of --user flag description - Maintains consistency with command descriptions

- Define help flag manually to override Cobra's default lowercase description - Ensures consistency with 'Help for Brev' instead of 'help for brev'

…mands

… descriptions

cloin · 2025-11-03T16:29:23Z

❯ ./brev -h

      brev client for managing instances

      Find more information at:
            https://brev.nvidia.com

Usage:
  brev [flags]
  brev [command]

Instance Commands:
  create                 Create a new instance
  delete                 Delete an instance
  ls                     List instances within active org

  The following commands have provider-dependent support:
  reset                  Reset an instance to recover from errors
  start                  Start an instance if it's stopped, or create one from url
  stop                   Stop an instance if it's running

Instance Access:
  copy                   Copy files and directories between local and remote instance
  open                   [beta] Open VSCode, Cursor, Windsurf, or tmux to your instance
  port-forward           Forward a port from instance to local machine
  shell                  [beta] Open a shell in your instance

Organization Management:
  invite                 Generate an invite link (alias for 'brev org invite')
  org                    Organization commands (run 'brev org --help' for subcommands)
  redeem                 Redeem a code for credits
  set                    Set active org (alias for 'brev org set')

Configuration:
  healthcheck            Check backend to see if it's healthy
  hello                  Get a quick onboarding of the Brev CLI
  login                  Log into Brev
  logout                 Log out of Brev
  profile                Personal profile commands
  refresh                Force a refresh to the SSH config
  ssh-key                Get your public SSH-Key

Flags:
  -h, --help              Help for Brev
      --no-check-latest   Do not check for the latest version when printing version
      --user string       Non root user to use for per user configuration of commands run as root
      --version           Print version output

Use "brev [command] --help" for more information about a command.

Co-authored-by: Pratik Patel <patel.s.pratik@gmail.com>

cloin requested a review from a team as a code owner October 31, 2025 18:08

cloin marked this pull request as draft October 31, 2025 18:09

cloin marked this pull request as ready for review October 31, 2025 20:07

cloin added 12 commits November 3, 2025 11:20

Hide dev-only commands from help output

e5d39bd

- Move 'fu' command to hidden annotation (inappropriate name, dev-only) - Move 'env-vars' to hidden annotation (redundant with configure-env-vars) - These commands remain functional but won't appear in help text

Hide non-functional secret command from help output

298debe

- Move 'secret' command to hidden annotation (non-functional) - Command remains available but won't appear in help text

Hide non-functional ollama command from help output

1a09a2e

- Move 'ollama' command to hidden annotation (non-functional) - Removes 'Quick Start' section from help (no longer needed) - Command remains available but won't appear in help text

Hide status command from help output

0a86898

Document invite and set as aliases in help text

016d019

- Update Short descriptions to indicate they are aliases for 'brev org invite' and 'brev org set' - This makes it clearer to users that these are convenience shortcuts

Capitalize flag descriptions for consistency

932dd01

- Capitalize first letter of --user flag description - Maintains consistency with command descriptions

Capitalize Brev in help flag description

b7c5bf9

- Define help flag manually to override Cobra's default lowercase description - Ensures consistency with 'Help for Brev' instead of 'help for brev'

Hide internal commands and update workspace to instance in help text

4ea0f5c

Add provider-dependent support warning for start, stop, and reset com…

788c138

…mands

cloin force-pushed the restructure-cli-help branch from fa7b0ad to 788c138 Compare November 3, 2025 16:24

Update redeem command for new help structure and remove 'coupon' from…

ebe74c0

… descriptions

patelspratik reviewed Nov 3, 2025

View reviewed changes

Comment thread pkg/cmd/refresh/refresh.go Outdated

patelspratik previously approved these changes Nov 3, 2025

View reviewed changes

Update pkg/cmd/refresh/refresh.go

0acd0de

Co-authored-by: Pratik Patel <patel.s.pratik@gmail.com>

cloin dismissed patelspratik’s stale review via 0acd0de November 3, 2025 18:00

patelspratik approved these changes Nov 3, 2025

View reviewed changes

cloin merged commit e86e3cf into main Nov 3, 2025
9 checks passed

cloin deleted the restructure-cli-help branch November 3, 2025 18:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure CLI Help Output with Improved Categorization#265

Restructure CLI Help Output with Improved Categorization#265
cloin merged 14 commits into
mainfrom
restructure-cli-help

cloin commented Oct 31, 2025 •

edited

Loading

Uh oh!

cloin commented Oct 31, 2025

Uh oh!

kjw3 commented Oct 31, 2025

test

Uh oh!

kjw3 commented Oct 31, 2025

Uh oh!

theFong commented Oct 31, 2025

Uh oh!

cloin commented Nov 3, 2025

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

cloin commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before:

After:

Uh oh!

cloin commented Oct 31, 2025

test

Uh oh!

kjw3 commented Oct 31, 2025

test

Uh oh!

kjw3 commented Oct 31, 2025

Uh oh!

theFong commented Oct 31, 2025

Uh oh!

cloin commented Nov 3, 2025

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cloin commented Oct 31, 2025 •

edited

Loading