coder · ammario · Sep 8, 2023 · Sep 8, 2023
diff --git a/cli/cliui/cliui.go b/cli/cliui/cliui.go
@@ -51,6 +51,11 @@ var (
 	Blue    = color.Color("#5000ff")
 )
 
+// Color returns a color for the given string.
+func Color(s string) termenv.Color {
+	return color.Color(s)
+}
+
 func isTerm() bool {
 	return color != termenv.Ascii
 }

diff --git a/cli/help.go b/cli/help.go
@@ -17,8 +17,10 @@ import (
 	"golang.org/x/crypto/ssh/terminal"
 	"golang.org/x/xerrors"
 
+	"github.com/coder/coder/v2/buildinfo"
 	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/pretty"
 )
 
 //go:embed help.tpl
@@ -47,12 +49,28 @@ func wrapTTY(s string) string {
 var usageTemplate = template.Must(
 	template.New("usage").Funcs(
 		template.FuncMap{
+			"version": func() string {
+				return buildinfo.Version()
+			},
 			"wrapTTY": func(s string) string {
 				return wrapTTY(s)
 			},
 			"trimNewline": func(s string) string {
 				return strings.TrimSuffix(s, "\n")
 			},
+			"keyword": func(s string) string {
+				return pretty.Sprint(
+					pretty.FgColor(cliui.Color("#0173ff")),
+					s,
+				)
+			},
+			"prettyHeader": func(s string) string {
+				return pretty.Sprint(
+					pretty.FgColor(
+						cliui.Color("#ffb500"),
+					), strings.ToUpper(s), ":",
+				)
+			},
 			"typeHelper": func(opt *clibase.Option) string {
 				switch v := opt.Value.(type) {
 				case *clibase.Enum:
@@ -71,13 +89,15 @@ var usageTemplate = template.Must(
 
 				body = wordwrap.WrapString(body, uint(twidth-len(spacing)))
 
+				sc := bufio.NewScanner(strings.NewReader(body))
+
 				var sb strings.Builder
-				for _, line := range strings.Split(body, "\n") {
+				for sc.Scan() {
 					// Remove existing indent, if any.
-					line = strings.TrimSpace(line)
+					// line = strings.TrimSpace(line)
 					// Use spaces so we can easily calculate wrapping.
 					_, _ = sb.WriteString(spacing)
-					_, _ = sb.WriteString(line)
+					_, _ = sb.Write(sc.Bytes())
 					_, _ = sb.WriteString("\n")
 				}
 				return sb.String()
@@ -126,9 +146,7 @@ var usageTemplate = template.Must(
 			"flagName": func(opt clibase.Option) string {
 				return opt.Flag
 			},
-			"prettyHeader": func(s string) string {
-				return cliui.Bold(s)
-			},
+
 			"isEnterprise": func(opt clibase.Option) bool {
 				return opt.Annotations.IsSet("enterprise")
 			},
@@ -160,12 +178,6 @@ var usageTemplate = template.Must(
 				}
 				return sb.String()
 			},
-			"formatLong": func(long string) string {
-				// We intentionally don't wrap here because it would misformat
-				// examples, where the new line would start without the prior
-				// line's indentation.
-				return strings.TrimSpace(long)
-			},
 			"formatGroupDescription": func(s string) string {
 				s = strings.ReplaceAll(s, "\n", "")
 				s = s + "\n"

diff --git a/cli/help.tpl b/cli/help.tpl
@@ -1,20 +1,22 @@
-{{- /* Heavily inspired by the Go toolchain formatting. */ -}}
-Usage: {{.FullUsage}}
+{{- /* Heavily inspired by the Go toolchain and fd */ -}}
+coder {{version}}
+
+{{prettyHeader "Usage"}}
+{{indent .FullUsage 2}}
 
 
 {{ with .Short }}
-{{- wrapTTY . }}
+{{- indent . 2 | wrapTTY }}
 {{"\n"}}
 {{- end}}
 
 {{ with .Aliases }}
-{{ "\n" }}
-{{ "Aliases:"}} {{ joinStrings .}}
-{{ "\n" }}
+{{"  Aliases: "}} {{- joinStrings .}}
 {{- end }}
 
 {{- with .Long}}
-{{- formatLong . }}
+{{"\n"}}
+{{- indent . 2}}
 {{ "\n" }}
 {{- end }}
 {{ with visibleChildren . }}
@@ -34,11 +36,11 @@ Usage: {{.FullUsage}}
 {{- else }}
 {{- end }}
     {{- range $index, $option := $group.Options }}
-	{{- if not (eq $option.FlagShorthand "") }}{{- print "\n  -" $option.FlagShorthand ", " -}}
+	{{- if not (eq $option.FlagShorthand "") }}{{- print "\n "}} {{ keyword "-"}}{{keyword $option.FlagShorthand }}{{", "}}
 	{{- else }}{{- print "\n      " -}}
 	{{- end }}
-    {{- with flagName $option }}--{{ . }}{{ end }} {{- with typeHelper $option }} {{ . }}{{ end }}
-    {{- with envName $option }}, ${{ . }}{{ end }}
+    {{- with flagName $option }}{{keyword "--"}}{{ keyword . }}{{ end }} {{- with typeHelper $option }} {{ . }}{{ end }}
+    {{- with envName $option }}, {{ print "$" . | keyword }}{{ end }}
     {{- with $option.Default }} (default: {{ . }}){{ end }}
         {{- with $option.Description }}
             {{- $desc := $option.Description }}
@@ -47,7 +49,7 @@ Usage: {{.FullUsage}}
         {{- end -}}
     {{- end }}
 {{- end }}
----
+———
 {{- if .Parent }}
 Run `coder --help` for a list of global options.
 {{- else }}

diff --git a/cli/testdata/coder_--help.golden b/cli/testdata/coder_--help.golden
@@ -1,15 +1,19 @@
-Usage: coder [global-flags] <subcommand>
-
-Coder v0.0.0-devel — A tool for provisioning self-hosted development environments with Terraform.
-  - Start a Coder server:
-
-     $ coder server
-
-  - Get started by creating a template from an example:
-
-     $ coder templates init
-
-[1mSubcommands[0m
+coder v0.0.0-devel
+
+[93mUSAGE:[0m
+  coder [global-flags] <subcommand>
+
+  Coder v0.0.0-devel — A tool for provisioning self-hosted development
+  environments with Terraform.
+    - Start a Coder server:
+
+       $ coder server
+
+    - Get started by creating a template from an example:
+
+       $ coder templates init
+
+[93mSUBCOMMANDS:[0m
     config-ssh        Add an SSH Host entry for your workspaces "ssh
                       coder.workspace"
     create            Create a workspace
@@ -45,43 +49,43 @@ Coder v0.0.0-devel — A tool for provisioning self-hosted development environme
     users             Manage users
     version           Show coder version
 
-[1mGlobal Options[0m 
+[93mGLOBAL OPTIONS:[0m 
 Global options are applied to all commands. They can be set using environment
 variables or flags.
 
-      --debug-options bool
+      [94m--[0m[94mdebug-options[0m bool
           Print all options, how they're set, then exit.
 
-      --disable-direct-connections bool, $CODER_DISABLE_DIRECT_CONNECTIONS
+      [94m--[0m[94mdisable-direct-connections[0m bool, [94m$CODER_DISABLE_DIRECT_CONNECTIONS[0m
           Disable direct (P2P) connections to workspaces.
 
-      --global-config string, $CODER_CONFIG_DIR (default: ~/.config/coderv2)
+      [94m--[0m[94mglobal-config[0m string, [94m$CODER_CONFIG_DIR[0m (default: ~/.config/coderv2)
           Path to the global `coder` config directory.
 
-      --header string-array, $CODER_HEADER
+      [94m--[0m[94mheader[0m string-array, [94m$CODER_HEADER[0m
           Additional HTTP headers added to all requests. Provide as key=value.
           Can be specified multiple times.
 
-      --header-command string, $CODER_HEADER_COMMAND
+      [94m--[0m[94mheader-command[0m string, [94m$CODER_HEADER_COMMAND[0m
           An external command that outputs additional HTTP headers added to all
           requests. The command must output each header as `key=value` on its
           own line.
 
-      --no-feature-warning bool, $CODER_NO_FEATURE_WARNING
+      [94m--[0m[94mno-feature-warning[0m bool, [94m$CODER_NO_FEATURE_WARNING[0m
           Suppress warnings about unlicensed features.
 
-      --no-version-warning bool, $CODER_NO_VERSION_WARNING
+      [94m--[0m[94mno-version-warning[0m bool, [94m$CODER_NO_VERSION_WARNING[0m
           Suppress warning when client and server versions do not match.
 
-      --token string, $CODER_SESSION_TOKEN
+      [94m--[0m[94mtoken[0m string, [94m$CODER_SESSION_TOKEN[0m
           Specify an authentication token. For security reasons setting
           CODER_SESSION_TOKEN is preferred.
 
-      --url url, $CODER_URL
+      [94m--[0m[94murl[0m url, [94m$CODER_URL[0m
           URL to a deployment.
 
-  -v, --verbose bool, $CODER_VERBOSE
+  [94m-[0m[94mv[0m, [94m--[0m[94mverbose[0m bool, [94m$CODER_VERBOSE[0m
           Enable verbose output.
 
----
+———
 Report bugs and request features at https://github.com/coder/coder/issues/new
diff --git a/cli/testdata/coder_agent_--help.golden b/cli/testdata/coder_agent_--help.golden
@@ -1,41 +1,44 @@
-Usage: coder agent [flags]
+coder v0.0.0-devel
 
-Starts the Coder workspace agent.
+[93mUSAGE:[0m
+  coder agent [flags]
 
-[1mOptions[0m
-      --log-human string, $CODER_AGENT_LOGGING_HUMAN (default: /dev/stderr)
+  Starts the Coder workspace agent.
+
+[93mOPTIONS:[0m
+      [94m--[0m[94mlog-human[0m string, [94m$CODER_AGENT_LOGGING_HUMAN[0m (default: /dev/stderr)
           Output human-readable logs to a given file.
 
-      --log-json string, $CODER_AGENT_LOGGING_JSON
+      [94m--[0m[94mlog-json[0m string, [94m$CODER_AGENT_LOGGING_JSON[0m
           Output JSON logs to a given file.
 
-      --log-stackdriver string, $CODER_AGENT_LOGGING_STACKDRIVER
+      [94m--[0m[94mlog-stackdriver[0m string, [94m$CODER_AGENT_LOGGING_STACKDRIVER[0m
           Output Stackdriver compatible logs to a given file.
 
-      --auth string, $CODER_AGENT_AUTH (default: token)
+      [94m--[0m[94mauth[0m string, [94m$CODER_AGENT_AUTH[0m (default: token)
           Specify the authentication type to use for the agent.
 
-      --debug-address string, $CODER_AGENT_DEBUG_ADDRESS (default: 127.0.0.1:2113)
+      [94m--[0m[94mdebug-address[0m string, [94m$CODER_AGENT_DEBUG_ADDRESS[0m (default: 127.0.0.1:2113)
           The bind address to serve a debug HTTP server.
 
-      --log-dir string, $CODER_AGENT_LOG_DIR (default: /tmp)
+      [94m--[0m[94mlog-dir[0m string, [94m$CODER_AGENT_LOG_DIR[0m (default: /tmp)
           Specify the location for the agent log files.
 
-      --no-reap bool
+      [94m--[0m[94mno-reap[0m bool
           Do not start a process reaper.
 
-      --pprof-address string, $CODER_AGENT_PPROF_ADDRESS (default: 127.0.0.1:6060)
+      [94m--[0m[94mpprof-address[0m string, [94m$CODER_AGENT_PPROF_ADDRESS[0m (default: 127.0.0.1:6060)
           The address to serve pprof.
 
-      --prometheus-address string, $CODER_AGENT_PROMETHEUS_ADDRESS (default: 127.0.0.1:2112)
+      [94m--[0m[94mprometheus-address[0m string, [94m$CODER_AGENT_PROMETHEUS_ADDRESS[0m (default: 127.0.0.1:2112)
           The bind address to serve Prometheus metrics.
 
-      --ssh-max-timeout duration, $CODER_AGENT_SSH_MAX_TIMEOUT (default: 72h)
+      [94m--[0m[94mssh-max-timeout[0m duration, [94m$CODER_AGENT_SSH_MAX_TIMEOUT[0m (default: 72h)
           Specify the max timeout for a SSH connection, it is advisable to set
           it to a minimum of 60s, but no more than 72h.
 
-      --tailnet-listen-port int, $CODER_AGENT_TAILNET_LISTEN_PORT (default: 0)
+      [94m--[0m[94mtailnet-listen-port[0m int, [94m$CODER_AGENT_TAILNET_LISTEN_PORT[0m (default: 0)
           Specify a static port for Tailscale to use for listening.
 
----
+———
 Run `coder --help` for a list of global options.
diff --git a/cli/testdata/coder_config-ssh_--help.golden b/cli/testdata/coder_config-ssh_--help.golden
@@ -1,51 +1,55 @@
-Usage: coder config-ssh [flags]
+coder v0.0.0-devel
 
-Add an SSH Host entry for your workspaces "ssh coder.workspace"
+[93mUSAGE:[0m
+  coder config-ssh [flags]
 
-- You can use -o (or --ssh-option) so set SSH options to be used for all your
-workspaces:
+  Add an SSH Host entry for your workspaces "ssh coder.workspace"
 
-     $ coder config-ssh -o ForwardAgent=yes
+    - You can use -o (or --ssh-option) so set SSH options to be used for all
+  your
+  workspaces:
+
+       $ coder config-ssh -o ForwardAgent=yes
+
+    - You can use --dry-run (or -n) to see the changes that would be made:
+
+       $ coder config-ssh --dry-run
 
-  - You can use --dry-run (or -n) to see the changes that would be made:
-
-     $ coder config-ssh --dry-run
-
-[1mOptions[0m
-      --coder-binary-path string, $CODER_SSH_CONFIG_BINARY_PATH
+[93mOPTIONS:[0m
+      [94m--[0m[94mcoder-binary-path[0m string, [94m$CODER_SSH_CONFIG_BINARY_PATH[0m
           Optionally specify the absolute path to the coder binary used in
           ProxyCommand. By default, the binary invoking this command ('config
           ssh') is used.
 
-  -n, --dry-run bool, $CODER_SSH_DRY_RUN
+  [94m-[0m[94mn[0m, [94m--[0m[94mdry-run[0m bool, [94m$CODER_SSH_DRY_RUN[0m
           Perform a trial run with no changes made, showing a diff at the end.
 
-      --force-unix-filepaths bool, $CODER_CONFIGSSH_UNIX_FILEPATHS
+      [94m--[0m[94mforce-unix-filepaths[0m bool, [94m$CODER_CONFIGSSH_UNIX_FILEPATHS[0m
           By default, 'config-ssh' uses the os path separator when writing the
           ssh config. This might be an issue in Windows machine that use a
           unix-like shell. This flag forces the use of unix file paths (the
           forward slash '/').
 
-      --ssh-config-file string, $CODER_SSH_CONFIG_FILE (default: ~/.ssh/config)
+      [94m--[0m[94mssh-config-file[0m string, [94m$CODER_SSH_CONFIG_FILE[0m (default: ~/.ssh/config)
           Specifies the path to an SSH config.
 
-      --ssh-host-prefix string, $CODER_CONFIGSSH_SSH_HOST_PREFIX
+      [94m--[0m[94mssh-host-prefix[0m string, [94m$CODER_CONFIGSSH_SSH_HOST_PREFIX[0m
           Override the default host prefix.
 
-  -o, --ssh-option string-array, $CODER_SSH_CONFIG_OPTS
+  [94m-[0m[94mo[0m, [94m--[0m[94mssh-option[0m string-array, [94m$CODER_SSH_CONFIG_OPTS[0m
           Specifies additional SSH options to embed in each host stanza.
 
-      --use-previous-options bool, $CODER_SSH_USE_PREVIOUS_OPTIONS
+      [94m--[0m[94muse-previous-options[0m bool, [94m$CODER_SSH_USE_PREVIOUS_OPTIONS[0m
           Specifies whether or not to keep options from previous run of
           config-ssh.
 
-      --wait yes|no|auto, $CODER_CONFIGSSH_WAIT (default: auto)
+      [94m--[0m[94mwait[0m yes|no|auto, [94m$CODER_CONFIGSSH_WAIT[0m (default: auto)
           Specifies whether or not to wait for the startup script to finish
           executing. Auto means that the agent startup script behavior
           configured in the workspace template is used.
 
-  -y, --yes bool
+  [94m-[0m[94my[0m, [94m--[0m[94myes[0m bool
           Bypass prompts.
 
----
+———
 Run `coder --help` for a list of global options.