diff --git a/cli/deployment/config.go b/cli/deployment/config.go index 41f53eb600fd2..9a18e9920bec5 100644 --- a/cli/deployment/config.go +++ b/cli/deployment/config.go @@ -467,6 +467,7 @@ func newConfig() *codersdk.DeploymentConfig { Usage: "Disables all rate limits. This is not recommended in production.", Flag: "dangerous-disable-rate-limits", Default: false, + Hidden: true, }, API: &codersdk.DeploymentConfigField[int]{ Name: "API Rate Limit", @@ -476,6 +477,7 @@ func newConfig() *codersdk.DeploymentConfig { EnvOverride: "CODER_API_RATE_LIMIT", Flag: "api-rate-limit", Default: 512, + Hidden: true, }, }, // DEPRECATED: use Experiments instead. @@ -538,12 +540,14 @@ func newConfig() *codersdk.DeploymentConfig { Usage: "Allow workspace apps that are not served from subdomains to be shared. Path-based app sharing is DISABLED by default for security purposes. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security.", Flag: "dangerous-allow-path-app-sharing", Default: false, + Hidden: true, }, AllowPathAppSiteOwnerAccess: &codersdk.DeploymentConfigField[bool]{ Name: "DANGEROUS: Allow Site Owners to Access Path Apps", Usage: "Allow site-owners to access workspace apps from workspaces they do not own. Owners cannot access path-based apps they do not own by default. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security.", Flag: "dangerous-allow-path-app-site-owner-access", Default: false, + Hidden: true, }, }, DisablePathApps: &codersdk.DeploymentConfigField[bool]{ diff --git a/cli/root.go b/cli/root.go index 254368a01d97d..3e9b5c6a6a689 100644 --- a/cli/root.go +++ b/cli/root.go @@ -14,7 +14,6 @@ import ( "runtime" "strings" "syscall" - "text/template" "time" "golang.org/x/xerrors" @@ -440,122 +439,6 @@ func isTTYWriter(cmd *cobra.Command, writer func() io.Writer) bool { return isatty.IsTerminal(file.Fd()) } -var templateFunctions = template.FuncMap{ - "usageHeader": usageHeader, - "isWorkspaceCommand": isWorkspaceCommand, -} - -func usageHeader(s string) string { - // Customizes the color of headings to make subcommands more visually - // appealing. - return cliui.Styles.Placeholder.Render(s) -} - -func isWorkspaceCommand(cmd *cobra.Command) bool { - if _, ok := cmd.Annotations["workspaces"]; ok { - return true - } - var ws bool - cmd.VisitParents(func(cmd *cobra.Command) { - if _, ok := cmd.Annotations["workspaces"]; ok { - ws = true - } - }) - return ws -} - -func usageTemplate() string { - // usageHeader is defined in init(). - return `{{usageHeader "Usage:"}} -{{- if .Runnable}} - {{.UseLine}} -{{end}} -{{- if .HasAvailableSubCommands}} - {{.CommandPath}} [command] -{{end}} - -{{- if gt (len .Aliases) 0}} -{{usageHeader "Aliases:"}} - {{.NameAndAliases}} -{{end}} - -{{- if .HasExample}} -{{usageHeader "Get Started:"}} -{{.Example}} -{{end}} - -{{- $isRootHelp := (not .HasParent)}} -{{- if .HasAvailableSubCommands}} -{{usageHeader "Commands:"}} - {{- range .Commands}} - {{- $isRootWorkspaceCommand := (and $isRootHelp (isWorkspaceCommand .))}} - {{- if (or (and .IsAvailableCommand (not $isRootWorkspaceCommand)) (eq .Name "help"))}} - {{rpad .Name .NamePadding }} {{.Short}} - {{- end}} - {{- end}} -{{end}} - -{{- if (and $isRootHelp .HasAvailableSubCommands)}} -{{usageHeader "Workspace Commands:"}} - {{- range .Commands}} - {{- if (and .IsAvailableCommand (isWorkspaceCommand .))}} - {{rpad .Name .NamePadding }} {{.Short}} - {{- end}} - {{- end}} -{{end}} - -{{- if .HasAvailableLocalFlags}} -{{usageHeader "Flags:"}} -{{.LocalFlags.FlagUsagesWrapped 100 | trimTrailingWhitespaces}} -{{end}} - -{{- if .HasAvailableInheritedFlags}} -{{usageHeader "Global Flags:"}} -{{.InheritedFlags.FlagUsagesWrapped 100 | trimTrailingWhitespaces}} -{{end}} - -{{- if .HasHelpSubCommands}} -{{usageHeader "Additional help topics:"}} - {{- range .Commands}} - {{- if .IsAdditionalHelpTopicCommand}} - {{rpad .CommandPath .CommandPathPadding}} {{.Short}} - {{- end}} - {{- end}} -{{end}} - -{{- if .HasAvailableSubCommands}} -Use "{{.CommandPath}} [command] --help" for more information about a command. -{{end}}` -} - -// example represents a standard example for command usage, to be used -// with formatExamples. -type example struct { - Description string - Command string -} - -// formatExamples formats the examples as width wrapped bulletpoint -// descriptions with the command underneath. -func formatExamples(examples ...example) string { - wrap := cliui.Styles.Wrap.Copy() - wrap.PaddingLeft(4) - var sb strings.Builder - for i, e := range examples { - if len(e.Description) > 0 { - _, _ = sb.WriteString(" - " + wrap.Render(e.Description + ":")[4:] + "\n\n ") - } - // We add 1 space here because `cliui.Styles.Code` adds an extra - // space. This makes the code block align at an even 2 or 6 - // spaces for symmetry. - _, _ = sb.WriteString(" " + cliui.Styles.Code.Render(fmt.Sprintf("$ %s", e.Command))) - if i < len(examples)-1 { - _, _ = sb.WriteString("\n\n") - } - } - return sb.String() -} - // FormatCobraError colorizes and adds "--help" docs to cobra commands. func FormatCobraError(err error, cmd *cobra.Command) string { helpErrMsg := fmt.Sprintf("Run '%s --help' for usage.", cmd.CommandPath()) diff --git a/cli/testdata/coder_--help.golden b/cli/testdata/coder_--help.golden index 6881d4320f098..80d50ff2815c8 100644 --- a/cli/testdata/coder_--help.golden +++ b/cli/testdata/coder_--help.golden @@ -47,19 +47,19 @@ Workspace Commands: stop Stop a workspace update Update a workspace -Flags: +Auth Flags: + --token string Specify an authentication token. For security reasons setting + CODER_SESSION_TOKEN is preferred. + Consumes $CODER_SESSION_TOKEN +Other Flags: --global-config coder Path to the global coder config directory. Consumes $CODER_CONFIG_DIR (default "~/.config/coderv2") --header stringArray HTTP headers added to all requests. Provide as "Key=Value". Consumes $CODER_HEADER - -h, --help help for coder --no-feature-warning Suppress warnings about unlicensed features. Consumes $CODER_NO_FEATURE_WARNING --no-version-warning Suppress warning when client and server versions do not match. Consumes $CODER_NO_VERSION_WARNING - --token string Specify an authentication token. For security reasons setting - CODER_SESSION_TOKEN is preferred. - Consumes $CODER_SESSION_TOKEN --url string URL to a deployment. Consumes $CODER_URL -v, --verbose Enable verbose output. diff --git a/cli/testdata/coder_agent_--help.golden b/cli/testdata/coder_agent_--help.golden index 2577cd660ed80..2b10e4dbed73c 100644 --- a/cli/testdata/coder_agent_--help.golden +++ b/cli/testdata/coder_agent_--help.golden @@ -1,15 +1,16 @@ Usage: coder agent [flags] -Flags: +Auth Flags: --auth string Specify the authentication type to use for the agent. Consumes $CODER_AGENT_AUTH (default "token") - -h, --help help for agent +Operability Flags: --log-dir string Specify the location for the agent log files. Consumes $CODER_AGENT_LOG_DIR (default "/tmp") - --no-reap Do not start a process reaper. --pprof-address string The address to serve pprof. Consumes $CODER_AGENT_PPROF_ADDRESS (default "127.0.0.1:6060") +Other Flags: + --no-reap Do not start a process reaper. Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_config-ssh_--help.golden b/cli/testdata/coder_config-ssh_--help.golden index b088c8586bc5b..444e2aba281d1 100644 --- a/cli/testdata/coder_config-ssh_--help.golden +++ b/cli/testdata/coder_config-ssh_--help.golden @@ -16,7 +16,6 @@ Get Started: Flags: -n, --dry-run Perform a trial run with no changes made, showing a diff at the end. - -h, --help help for config-ssh --ssh-config-file string Specifies the path to an SSH config. Consumes $CODER_SSH_CONFIG_FILE (default "~/.ssh/config") -o, --ssh-option stringArray Specifies additional SSH options to embed in each host stanza. diff --git a/cli/testdata/coder_create_--help.golden b/cli/testdata/coder_create_--help.golden index 6be1ea35363e0..9250e7f96dbde 100644 --- a/cli/testdata/coder_create_--help.golden +++ b/cli/testdata/coder_create_--help.golden @@ -4,7 +4,6 @@ Usage: coder create [name] [flags] Flags: - -h, --help help for create --parameter-file string Specify a file path with parameter values. Consumes $CODER_PARAMETER_FILE --rich-parameter-file string Specify a file path with values for rich diff --git a/cli/testdata/coder_delete_--help.golden b/cli/testdata/coder_delete_--help.golden index 9b25a441eb247..a5aef6e73570e 100644 --- a/cli/testdata/coder_delete_--help.golden +++ b/cli/testdata/coder_delete_--help.golden @@ -7,7 +7,6 @@ Aliases: delete, rm Flags: - -h, --help help for delete --orphan Delete a workspace without deleting its resources. This can delete a workspace in a broken state, but may also lead to unaccounted cloud resources. -y, --yes Bypass prompts diff --git a/cli/testdata/coder_dotfiles_--help.golden b/cli/testdata/coder_dotfiles_--help.golden index 4db2317705566..9132210bbac4e 100644 --- a/cli/testdata/coder_dotfiles_--help.golden +++ b/cli/testdata/coder_dotfiles_--help.golden @@ -9,7 +9,6 @@ Get Started: $ coder dotfiles --yes git@github.com:example/dotfiles.git Flags: - -h, --help help for dotfiles --symlink-dir string Specifies the directory for the dotfiles symlink destinations. If empty will use $HOME. Consumes $CODER_SYMLINK_DIR diff --git a/cli/testdata/coder_list_--help.golden b/cli/testdata/coder_list_--help.golden index 62ed092d6d228..6b6b26d546226 100644 --- a/cli/testdata/coder_list_--help.golden +++ b/cli/testdata/coder_list_--help.golden @@ -12,7 +12,6 @@ Flags: template, status, last built, outdated, starts at, stops after (default [workspace,template,status,last built,outdated,starts at,stops after]) - -h, --help help for list -o, --output string Output format. Available formats: table, json (default "table") --search string Search for a workspace with a query. (default "owner:me") diff --git a/cli/testdata/coder_login_--help.golden b/cli/testdata/coder_login_--help.golden index cbec6869dfa06..235d0f4a16247 100644 --- a/cli/testdata/coder_login_--help.golden +++ b/cli/testdata/coder_login_--help.golden @@ -16,7 +16,6 @@ Flags: --first-user-username string Specifies a username to use if creating the first user for the deployment. Consumes $CODER_FIRST_USER_USERNAME - -h, --help help for login Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_logout_--help.golden b/cli/testdata/coder_logout_--help.golden index 3714b020ea892..99f370b2d36e8 100644 --- a/cli/testdata/coder_logout_--help.golden +++ b/cli/testdata/coder_logout_--help.golden @@ -4,7 +4,6 @@ Usage: coder logout [flags] Flags: - -h, --help help for logout -y, --yes Bypass prompts Global Flags: diff --git a/cli/testdata/coder_ping_--help.golden b/cli/testdata/coder_ping_--help.golden index 430d561bda19a..5d1488da6284f 100644 --- a/cli/testdata/coder_ping_--help.golden +++ b/cli/testdata/coder_ping_--help.golden @@ -4,7 +4,6 @@ Usage: coder ping [flags] Flags: - -h, --help help for ping -n, --num int Specifies the number of pings to perform. (default 10) -t, --timeout duration Specifies how long to wait for a ping to complete. (default 5s) -v, --verbose Enables verbose logging. diff --git a/cli/testdata/coder_port-forward_--help.golden b/cli/testdata/coder_port-forward_--help.golden index a61f2cb109b32..f790140091e79 100644 --- a/cli/testdata/coder_port-forward_--help.golden +++ b/cli/testdata/coder_port-forward_--help.golden @@ -26,7 +26,6 @@ Get Started: $ coder port-forward --tcp 8080,9000:3000,9090-9092,10000-10002:10010-10012 Flags: - -h, --help help for port-forward -p, --tcp stringArray Forward TCP port(s) from the workspace to the local machine. Consumes $CODER_PORT_FORWARD_TCP --udp stringArray Forward UDP port(s) from the workspace to the local machine. The UDP diff --git a/cli/testdata/coder_publickey_--help.golden b/cli/testdata/coder_publickey_--help.golden index f8b8f169dec9f..8ab915f09a494 100644 --- a/cli/testdata/coder_publickey_--help.golden +++ b/cli/testdata/coder_publickey_--help.golden @@ -7,7 +7,6 @@ Aliases: publickey, pubkey Flags: - -h, --help help for publickey --reset Regenerate your public key. This will require updating the key on any services it's registered with. -y, --yes Bypass prompts diff --git a/cli/testdata/coder_rename_--help.golden b/cli/testdata/coder_rename_--help.golden index 54bf48b302eb4..1801ed86e1c46 100644 --- a/cli/testdata/coder_rename_--help.golden +++ b/cli/testdata/coder_rename_--help.golden @@ -4,7 +4,6 @@ Usage: coder rename [flags] Flags: - -h, --help help for rename -y, --yes Bypass prompts Global Flags: diff --git a/cli/testdata/coder_reset-password_--help.golden b/cli/testdata/coder_reset-password_--help.golden index 1a99639c5765e..a3aa7489a5165 100644 --- a/cli/testdata/coder_reset-password_--help.golden +++ b/cli/testdata/coder_reset-password_--help.golden @@ -4,7 +4,6 @@ Usage: coder reset-password [flags] Flags: - -h, --help help for reset-password --postgres-url string URL of a PostgreSQL database to connect to. Consumes $CODER_PG_CONNECTION_URL diff --git a/cli/testdata/coder_restart_--help.golden b/cli/testdata/coder_restart_--help.golden index afea82201ce55..d790983838364 100644 --- a/cli/testdata/coder_restart_--help.golden +++ b/cli/testdata/coder_restart_--help.golden @@ -4,7 +4,6 @@ Usage: coder restart [flags] Flags: - -h, --help help for restart -y, --yes Bypass prompts Global Flags: diff --git a/cli/testdata/coder_scaletest_--help.golden b/cli/testdata/coder_scaletest_--help.golden index 8949adc8a5df0..5307e040e563f 100644 --- a/cli/testdata/coder_scaletest_--help.golden +++ b/cli/testdata/coder_scaletest_--help.golden @@ -9,8 +9,7 @@ Commands: cleanup Cleanup any orphaned scaletest resources create-workspaces Creates many workspaces and waits for them to be ready -Flags: - -h, --help help for scaletest + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_scaletest_cleanup_--help.golden b/cli/testdata/coder_scaletest_cleanup_--help.golden index a0a05274f36dd..7470f541a2284 100644 --- a/cli/testdata/coder_scaletest_cleanup_--help.golden +++ b/cli/testdata/coder_scaletest_cleanup_--help.golden @@ -12,7 +12,6 @@ Flags: Consumes $CODER_LOADTEST_CLEANUP_JOB_TIMEOUT (default 5m0s) --cleanup-timeout duration Timeout for the entire cleanup run. 0 means unlimited. Consumes $CODER_LOADTEST_CLEANUP_TIMEOUT (default 30m0s) - -h, --help help for cleanup Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_scaletest_create-workspaces_--help.golden b/cli/testdata/coder_scaletest_create-workspaces_--help.golden index 0c07f92735093..93411946ef8ef 100644 --- a/cli/testdata/coder_scaletest_create-workspaces_--help.golden +++ b/cli/testdata/coder_scaletest_create-workspaces_--help.golden @@ -5,7 +5,26 @@ It is recommended that all rate limits are disabled on the server before running Usage: coder scaletest create-workspaces [flags] -Flags: +Operability Flags: + --trace Whether application tracing data is collected. It + exports to a backend configured by environment + variables. See: + https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md. + Consumes $CODER_LOADTEST_TRACE + --trace-coder Whether opentelemetry traces are sent to Coder. + We recommend keeping this disabled unless we + advise you to enable it. + Consumes $CODER_LOADTEST_TRACE_CODER + --trace-honeycomb-api-key string Enables trace exporting to Honeycomb.io using the + provided API key. + Consumes $CODER_LOADTEST_TRACE_HONEYCOMB_API_KEY + --trace-propagate Enables trace propagation to the Coder backend, + which will be used to correlate server-side spans + with client-side spans. Only enable this if the + server is configured with the exact same tracing + configuration as the client. + Consumes $CODER_LOADTEST_TRACE_PROPAGATE +Other Flags: --cleanup-concurrency int Number of concurrent cleanup jobs to run. 0 means unlimited. Consumes $CODER_LOADTEST_CLEANUP_CONCURRENCY @@ -38,7 +57,6 @@ Flags: Consumes $CODER_LOADTEST_CONNECT_URL -c, --count int Required: Number of workspaces to create. Consumes $CODER_LOADTEST_COUNT (default 1) - -h, --help help for create-workspaces --job-timeout duration Timeout per job. Jobs may take longer to complete under higher concurrency limits. Consumes $CODER_LOADTEST_JOB_TIMEOUT (default 5m0s) @@ -94,24 +112,6 @@ Flags: --timeout duration Timeout for the entire test run. 0 means unlimited. Consumes $CODER_LOADTEST_TIMEOUT (default 30m0s) - --trace Whether application tracing data is collected. It - exports to a backend configured by environment - variables. See: - https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md. - Consumes $CODER_LOADTEST_TRACE - --trace-coder Whether opentelemetry traces are sent to Coder. - We recommend keeping this disabled unless we - advise you to enable it. - Consumes $CODER_LOADTEST_TRACE_CODER - --trace-honeycomb-api-key string Enables trace exporting to Honeycomb.io using the - provided API key. - Consumes $CODER_LOADTEST_TRACE_HONEYCOMB_API_KEY - --trace-propagate Enables trace propagation to the Coder backend, - which will be used to correlate server-side spans - with client-side spans. Only enable this if the - server is configured with the exact same tracing - configuration as the client. - Consumes $CODER_LOADTEST_TRACE_PROPAGATE Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_schedule_--help.golden b/cli/testdata/coder_schedule_--help.golden index 9018e6a2dede3..7c5ccafa48904 100644 --- a/cli/testdata/coder_schedule_--help.golden +++ b/cli/testdata/coder_schedule_--help.golden @@ -11,8 +11,7 @@ Commands: start Edit workspace start schedule stop Edit workspace stop schedule -Flags: - -h, --help help for schedule + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_schedule_override-stop_--help.golden b/cli/testdata/coder_schedule_override-stop_--help.golden index 8e5827e4fe129..4e3a5d3ffbfd9 100644 --- a/cli/testdata/coder_schedule_override-stop_--help.golden +++ b/cli/testdata/coder_schedule_override-stop_--help.golden @@ -9,8 +9,7 @@ Usage: Get Started: $ coder schedule override-stop my-workspace 90m -Flags: - -h, --help help for override-stop + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_schedule_show_--help.golden b/cli/testdata/coder_schedule_show_--help.golden index 3c2f4aba6e4e4..d9557a08aa5ed 100644 --- a/cli/testdata/coder_schedule_show_--help.golden +++ b/cli/testdata/coder_schedule_show_--help.golden @@ -7,8 +7,7 @@ Shows the following information for the given workspace: Usage: coder schedule show [flags] -Flags: - -h, --help help for show + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_schedule_start_--help.golden b/cli/testdata/coder_schedule_start_--help.golden index 1a2c137d42571..4ddc0ef23eeab 100644 --- a/cli/testdata/coder_schedule_start_--help.golden +++ b/cli/testdata/coder_schedule_start_--help.golden @@ -16,8 +16,7 @@ Get Started: $ coder schedule start my-workspace 9:30AM Mon-Fri Europe/Dublin -Flags: - -h, --help help for start + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_schedule_stop_--help.golden b/cli/testdata/coder_schedule_stop_--help.golden index f5fad8ebd933c..22d7bd0b01630 100644 --- a/cli/testdata/coder_schedule_stop_--help.golden +++ b/cli/testdata/coder_schedule_stop_--help.golden @@ -17,8 +17,7 @@ Usage: Get Started: $ coder schedule stop my-workspace 2h30m -Flags: - -h, --help help for stop + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_server_--help.golden b/cli/testdata/coder_server_--help.golden index 4a05a68c0faba..19ca85a809203 100644 --- a/cli/testdata/coder_server_--help.golden +++ b/cli/testdata/coder_server_--help.golden @@ -10,57 +10,11 @@ Commands: postgres-builtin-serve Run the built-in PostgreSQL deployment. postgres-builtin-url Output the connection URL for the built-in PostgreSQL deployment. -Flags: +Networking Flags: --access-url string External URL to access your deployment. This must be accessible by all provisioned workspaces. Consumes $CODER_ACCESS_URL - --api-rate-limit int Maximum number of requests per - minute allowed to the API per user, - or per IP address for - unauthenticated users. Negative - values mean no rate limit. Some API - endpoints have separate strict rate - limits regardless of this value to - prevent denial-of-service or brute - force attacks. - Consumes $CODER_API_RATE_LIMIT - (default 512) - --cache-dir string The directory to cache temporary - files. If unspecified and - $CACHE_DIRECTORY is set, it will be - used for compatibility with systemd. - Consumes $CODER_CACHE_DIRECTORY - (default "~/.cache/coder") - --dangerous-allow-path-app-sharing Allow workspace apps that are not - served from subdomains to be shared. - Path-based app sharing is DISABLED - by default for security purposes. - Path-based apps can make requests to - the Coder API and pose a security - risk when the workspace serves - malicious JavaScript. Path-based - apps can be disabled entirely with - --disable-path-apps for further - security. - Consumes - $CODER_DANGEROUS_ALLOW_PATH_APP_SHARING - --dangerous-allow-path-app-site-owner-access Allow site-owners to access - workspace apps from workspaces they - do not own. Owners cannot access - path-based apps they do not own by - default. Path-based apps can make - requests to the Coder API and pose a - security risk when the workspace - serves malicious JavaScript. - Path-based apps can be disabled - entirely with --disable-path-apps - for further security. - Consumes - $CODER_DANGEROUS_ALLOW_PATH_APP_SITE_OWNER_ACCESS - --dangerous-disable-rate-limits Disables all rate limits. This is - not recommended in production. - Consumes $CODER_RATE_LIMIT_DISABLE_ALL --derp-config-path string Path to read a DERP mapping from. See: https://tailscale.com/kb/1118/custom-derp-servers/ @@ -94,6 +48,105 @@ Flags: Consumes $CODER_DERP_SERVER_STUN_ADDRESSES (default [stun.l.google.com:19302]) + --wildcard-access-url is configured. + Consumes $CODER_DISABLE_PATH_APPS + --http-address string HTTP bind address of the server. + Unset to disable the HTTP endpoint. + Consumes $CODER_HTTP_ADDRESS + (default "127.0.0.1:3000") + --proxy-trusted-headers strings Headers to trust for forwarding IP + addresses. e.g. Cf-Connecting-Ip, + True-Client-Ip, X-Forwarded-For + Consumes $CODER_PROXY_TRUSTED_HEADERS + --proxy-trusted-origins strings Origin addresses to respect + "proxy-trusted-headers". e.g. + 192.168.1.0/24 + Consumes $CODER_PROXY_TRUSTED_ORIGINS + --redirect-to-access-url Specifies whether to redirect + requests that do not match the + access URL host. + Consumes $CODER_REDIRECT_TO_ACCESS_URL + --secure-auth-cookie Controls if the 'Secure' property is + set on browser session cookies. + Consumes $CODER_SECURE_AUTH_COOKIE + --strict-transport-security int Controls if the + 'Strict-Transport-Security' header + is set on all static file responses. + This header should only be set if + the server is accessed via HTTPS. + This value is the MaxAge in seconds + of the header. + Consumes $CODER_STRICT_TRANSPORT_SECURITY + --strict-transport-security-options strings Two optional fields can be set in + the Strict-Transport-Security + header; 'includeSubDomains' and + 'preload'. The + 'strict-transport-security' flag + must be set to a non-zero value for + these options to be used. + Consumes + $CODER_STRICT_TRANSPORT_SECURITY_OPTIONS + --telemetry Whether telemetry is enabled or not. + Coder collects anonymized usage data + to help improve our product. + Consumes $CODER_TELEMETRY_ENABLE + --telemetry-trace Whether Opentelemetry traces are + sent to Coder. Coder collects + anonymized application tracing to + help improve our product. Disabling + telemetry also disables this option. + Consumes $CODER_TELEMETRY_TRACE + --tls-address string HTTPS bind address of the server. + Consumes $CODER_TLS_ADDRESS (default + "127.0.0.1:3443") + --tls-cert-file strings Path to each certificate for TLS. It + requires a PEM-encoded file. To + configure the listener to use a CA + certificate, concatenate the primary + certificate and the CA certificate + together. The primary certificate + should appear first in the combined + file. + Consumes $CODER_TLS_CERT_FILE + --tls-client-auth string Policy the server will follow for + TLS Client Authentication. Accepted + values are "none", "request", + "require-any", "verify-if-given", or + "require-and-verify". + Consumes $CODER_TLS_CLIENT_AUTH + (default "none") + --tls-client-ca-file string PEM-encoded Certificate Authority + file used for checking the + authenticity of client + Consumes $CODER_TLS_CLIENT_CA_FILE + --tls-client-cert-file string Path to certificate for client TLS + authentication. It requires a + PEM-encoded file. + Consumes $CODER_TLS_CLIENT_CERT_FILE + --tls-client-key-file string Path to key for client TLS + authentication. It requires a + PEM-encoded file. + Consumes $CODER_TLS_CLIENT_KEY_FILE + --tls-enable Whether TLS will be enabled. + Consumes $CODER_TLS_ENABLE + --tls-key-file strings Paths to the private keys for each + of the certificates. It requires a + PEM-encoded file. + Consumes $CODER_TLS_KEY_FILE + --tls-min-version string Minimum supported version of TLS. + Accepted values are "tls10", + "tls11", "tls12" or "tls13" + Consumes $CODER_TLS_MIN_VERSION + (default "tls12") + --update-check Periodically check for new releases + of Coder and inform the owner. The + check is performed once per day. + Consumes $CODER_UPDATE_CHECK + --wildcard-access-url string Specifies the wildcard hostname to + use for workspace applications in + the form "*.example.com". + Consumes $CODER_WILDCARD_ACCESS_URL +Auth Flags: --disable-password-auth coder server create-admin Disable password authentication. This is recommended for security purposes in production deployments @@ -107,15 +160,6 @@ Flags: command to create a new admin user directly in the database. Consumes $CODER_DISABLE_PASSWORD_AUTH - --disable-path-apps Disable workspace apps that are not - served from subdomains. Path-based - apps can make requests to the Coder - API and pose a security risk when - the workspace serves malicious - JavaScript. This is recommended for - security purposes if a - --wildcard-access-url is configured. - Consumes $CODER_DISABLE_PATH_APPS --disable-session-expiry-refresh Disable automatic session expiry bumping due to activity. This forces all sessions to become invalid after @@ -123,26 +167,6 @@ Flags: reached. Consumes $CODER_DISABLE_SESSION_EXPIRY_REFRESH - --experiments strings Enable one or more experiments. - These are not ready for production. - Separate multiple experiments with - commas, or enter '*' to opt-in to - all available experiments. - Consumes $CODER_EXPERIMENTS - -h, --help help for server - --http-address string HTTP bind address of the server. - Unset to disable the HTTP endpoint. - Consumes $CODER_HTTP_ADDRESS - (default "127.0.0.1:3000") - --log-human string Output human-readable logs to a - given file. - Consumes $CODER_LOGGING_HUMAN - (default "/dev/stderr") - --log-json string Output JSON logs to a given file. - Consumes $CODER_LOGGING_JSON - --log-stackdriver string Output Stackdriver compatible logs - to a given file. - Consumes $CODER_LOGGING_STACKDRIVER --max-token-lifetime duration The maximum lifetime duration users can specify when creating an API token. @@ -212,14 +236,24 @@ Flags: username. Consumes $CODER_OIDC_USERNAME_FIELD (default "preferred_username") - --postgres-url string URL of a PostgreSQL database. If - empty, PostgreSQL binaries will be - downloaded from Maven - (https://repo1.maven.org/maven2) and - store all data in the config root. - Access the built-in database with - "coder server postgres-builtin-url". - Consumes $CODER_PG_CONNECTION_URL + --session-duration duration The token expiry duration for + browser sessions. Sessions may last + longer if they are actively making + requests, but this functionality can + be disabled via + --disable-session-expiry-refresh. + Consumes $CODER_MAX_SESSION_EXPIRY + (default 24h0m0s) +Operability Flags: + --log-human string Output human-readable logs to a + given file. + Consumes $CODER_LOGGING_HUMAN + (default "/dev/stderr") + --log-json string Output JSON logs to a given file. + Consumes $CODER_LOGGING_JSON + --log-stackdriver string Output Stackdriver compatible logs + to a given file. + Consumes $CODER_LOGGING_STACKDRIVER --pprof-address string The bind address to serve pprof. Consumes $CODER_PPROF_ADDRESS (default "127.0.0.1:6060") @@ -234,6 +268,26 @@ Flags: address defined by prometheus address. Consumes $CODER_PROMETHEUS_ENABLE + --trace Whether application tracing data is + collected. It exports to a backend + configured by environment variables. + See: + https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md + Consumes $CODER_TRACE_ENABLE + --trace-honeycomb-api-key string Enables trace exporting to + Honeycomb.io using the provided API + Key. + Consumes $CODER_TRACE_HONEYCOMB_API_KEY + --trace-logs Enables capturing of logs as events + in traces. This is useful for + debugging, but may result in a very + large amount of events being sent to + the tracing backend which may incur + significant costs. If the verbose + flag was supplied, debug-level logs + will be included. + Consumes $CODER_TRACE_CAPTURE_LOGS +Provisioning Flags: --provisioner-daemon-poll-interval duration Time to wait before polling for a new job. Consumes @@ -252,133 +306,42 @@ Flags: tasks that are stuck. Consumes $CODER_PROVISIONER_FORCE_CANCEL_INTERVAL (default 10m0s) - --proxy-trusted-headers strings Headers to trust for forwarding IP - addresses. e.g. Cf-Connecting-Ip, - True-Client-Ip, X-Forwarded-For - Consumes $CODER_PROXY_TRUSTED_HEADERS - --proxy-trusted-origins strings Origin addresses to respect - "proxy-trusted-headers". e.g. - 192.168.1.0/24 - Consumes $CODER_PROXY_TRUSTED_ORIGINS - --redirect-to-access-url Specifies whether to redirect - requests that do not match the - access URL host. - Consumes $CODER_REDIRECT_TO_ACCESS_URL - --secure-auth-cookie Controls if the 'Secure' property is - set on browser session cookies. - Consumes $CODER_SECURE_AUTH_COOKIE - --session-duration duration The token expiry duration for - browser sessions. Sessions may last - longer if they are actively making - requests, but this functionality can - be disabled via - --disable-session-expiry-refresh. - Consumes $CODER_MAX_SESSION_EXPIRY - (default 24h0m0s) +Other Flags: + --cache-dir string The directory to cache temporary + files. If unspecified and + $CACHE_DIRECTORY is set, it will be + used for compatibility with systemd. + Consumes $CODER_CACHE_DIRECTORY + (default "~/.cache/coder") + --disable-path-apps Disable workspace apps that are not + served from subdomains. Path-based + apps can make requests to the Coder + API and pose a security risk when + the workspace serves malicious + JavaScript. This is recommended for + security purposes if a + --experiments strings Enable one or more experiments. + These are not ready for production. + Separate multiple experiments with + commas, or enter '*' to opt-in to + all available experiments. + Consumes $CODER_EXPERIMENTS + --postgres-url string URL of a PostgreSQL database. If + empty, PostgreSQL binaries will be + downloaded from Maven + (https://repo1.maven.org/maven2) and + store all data in the config root. + Access the built-in database with + "coder server postgres-builtin-url". + Consumes $CODER_PG_CONNECTION_URL --ssh-keygen-algorithm string The algorithm to use for generating ssh keys. Accepted values are "ed25519", "ecdsa", or "rsa4096". Consumes $CODER_SSH_KEYGEN_ALGORITHM (default "ed25519") - --strict-transport-security int Controls if the - 'Strict-Transport-Security' header - is set on all static file responses. - This header should only be set if - the server is accessed via HTTPS. - This value is the MaxAge in seconds - of the header. - Consumes $CODER_STRICT_TRANSPORT_SECURITY - --strict-transport-security-options strings Two optional fields can be set in - the Strict-Transport-Security - header; 'includeSubDomains' and - 'preload'. The - 'strict-transport-security' flag - must be set to a non-zero value for - these options to be used. - Consumes - $CODER_STRICT_TRANSPORT_SECURITY_OPTIONS --swagger-enable Expose the swagger endpoint via /swagger. Consumes $CODER_SWAGGER_ENABLE - --telemetry Whether telemetry is enabled or not. - Coder collects anonymized usage data - to help improve our product. - Consumes $CODER_TELEMETRY_ENABLE - --telemetry-trace Whether Opentelemetry traces are - sent to Coder. Coder collects - anonymized application tracing to - help improve our product. Disabling - telemetry also disables this option. - Consumes $CODER_TELEMETRY_TRACE - --tls-address string HTTPS bind address of the server. - Consumes $CODER_TLS_ADDRESS (default - "127.0.0.1:3443") - --tls-cert-file strings Path to each certificate for TLS. It - requires a PEM-encoded file. To - configure the listener to use a CA - certificate, concatenate the primary - certificate and the CA certificate - together. The primary certificate - should appear first in the combined - file. - Consumes $CODER_TLS_CERT_FILE - --tls-client-auth string Policy the server will follow for - TLS Client Authentication. Accepted - values are "none", "request", - "require-any", "verify-if-given", or - "require-and-verify". - Consumes $CODER_TLS_CLIENT_AUTH - (default "none") - --tls-client-ca-file string PEM-encoded Certificate Authority - file used for checking the - authenticity of client - Consumes $CODER_TLS_CLIENT_CA_FILE - --tls-client-cert-file string Path to certificate for client TLS - authentication. It requires a - PEM-encoded file. - Consumes $CODER_TLS_CLIENT_CERT_FILE - --tls-client-key-file string Path to key for client TLS - authentication. It requires a - PEM-encoded file. - Consumes $CODER_TLS_CLIENT_KEY_FILE - --tls-enable Whether TLS will be enabled. - Consumes $CODER_TLS_ENABLE - --tls-key-file strings Paths to the private keys for each - of the certificates. It requires a - PEM-encoded file. - Consumes $CODER_TLS_KEY_FILE - --tls-min-version string Minimum supported version of TLS. - Accepted values are "tls10", - "tls11", "tls12" or "tls13" - Consumes $CODER_TLS_MIN_VERSION - (default "tls12") - --trace Whether application tracing data is - collected. It exports to a backend - configured by environment variables. - See: - https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md - Consumes $CODER_TRACE_ENABLE - --trace-honeycomb-api-key string Enables trace exporting to - Honeycomb.io using the provided API - Key. - Consumes $CODER_TRACE_HONEYCOMB_API_KEY - --trace-logs Enables capturing of logs as events - in traces. This is useful for - debugging, but may result in a very - large amount of events being sent to - the tracing backend which may incur - significant costs. If the verbose - flag was supplied, debug-level logs - will be included. - Consumes $CODER_TRACE_CAPTURE_LOGS - --update-check Periodically check for new releases - of Coder and inform the owner. The - check is performed once per day. - Consumes $CODER_UPDATE_CHECK - --wildcard-access-url string Specifies the wildcard hostname to - use for workspace applications in - the form "*.example.com". - Consumes $CODER_WILDCARD_ACCESS_URL Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_server_create-admin-user_--help.golden b/cli/testdata/coder_server_create-admin-user_--help.golden index 1ff1e939ae6ee..8764f0d980d29 100644 --- a/cli/testdata/coder_server_create-admin-user_--help.golden +++ b/cli/testdata/coder_server_create-admin-user_--help.golden @@ -6,7 +6,6 @@ Usage: Flags: --email string The email of the new user. If not specified, you will be prompted via stdin. Consumes $CODER_EMAIL. - -h, --help help for create-admin-user --password string The password of the new user. If not specified, you will be prompted via stdin. Consumes $CODER_PASSWORD. --postgres-url string URL of a PostgreSQL database. If empty, the built-in diff --git a/cli/testdata/coder_server_postgres-builtin-serve_--help.golden b/cli/testdata/coder_server_postgres-builtin-serve_--help.golden index 1bc7fd2fce7dc..35e81ae335404 100644 --- a/cli/testdata/coder_server_postgres-builtin-serve_--help.golden +++ b/cli/testdata/coder_server_postgres-builtin-serve_--help.golden @@ -4,7 +4,6 @@ Usage: coder server postgres-builtin-serve [flags] Flags: - -h, --help help for postgres-builtin-serve --raw-url Output the raw connection URL instead of a psql command. Global Flags: diff --git a/cli/testdata/coder_server_postgres-builtin-url_--help.golden b/cli/testdata/coder_server_postgres-builtin-url_--help.golden index 6fe19269dc8fa..daafadc0a77b0 100644 --- a/cli/testdata/coder_server_postgres-builtin-url_--help.golden +++ b/cli/testdata/coder_server_postgres-builtin-url_--help.golden @@ -4,7 +4,6 @@ Usage: coder server postgres-builtin-url [flags] Flags: - -h, --help help for postgres-builtin-url --raw-url Output the raw connection URL instead of a psql command. Global Flags: diff --git a/cli/testdata/coder_show_--help.golden b/cli/testdata/coder_show_--help.golden index 2f4f68c0d254c..c9cd6314e4f34 100644 --- a/cli/testdata/coder_show_--help.golden +++ b/cli/testdata/coder_show_--help.golden @@ -3,8 +3,7 @@ Display details of a workspace's resources and agents Usage: coder show [flags] -Flags: - -h, --help help for show + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_speedtest_--help.golden b/cli/testdata/coder_speedtest_--help.golden index fa8cb952a866c..6b54d5c125ac7 100644 --- a/cli/testdata/coder_speedtest_--help.golden +++ b/cli/testdata/coder_speedtest_--help.golden @@ -5,7 +5,6 @@ Usage: Flags: -d, --direct Specifies whether to wait for a direct connection before testing speed. - -h, --help help for speedtest -r, --reverse Specifies whether to run in reverse mode where the client receives and the server sends. -t, --time duration Specifies the duration to monitor traffic. (default 5s) diff --git a/cli/testdata/coder_ssh_--help.golden b/cli/testdata/coder_ssh_--help.golden index 20f5673b7de4a..8c80abc44717e 100644 --- a/cli/testdata/coder_ssh_--help.golden +++ b/cli/testdata/coder_ssh_--help.golden @@ -15,7 +15,6 @@ Flags: a GPG agent is already running in the workspace, it will be attempted to be killed. Consumes $CODER_SSH_FORWARD_GPG - -h, --help help for ssh --identity-agent string Specifies which identity agent to use (overrides $SSH_AUTH_SOCK), forward agent must also be enabled. diff --git a/cli/testdata/coder_start_--help.golden b/cli/testdata/coder_start_--help.golden index ced86097073c6..d136b596c424a 100644 --- a/cli/testdata/coder_start_--help.golden +++ b/cli/testdata/coder_start_--help.golden @@ -4,7 +4,6 @@ Usage: coder start [flags] Flags: - -h, --help help for start -y, --yes Bypass prompts Global Flags: diff --git a/cli/testdata/coder_state_--help.golden b/cli/testdata/coder_state_--help.golden index af5833729ddd1..d7a4496e94e39 100644 --- a/cli/testdata/coder_state_--help.golden +++ b/cli/testdata/coder_state_--help.golden @@ -9,8 +9,7 @@ Commands: pull push -Flags: - -h, --help help for state + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_state_pull_--help.golden b/cli/testdata/coder_state_pull_--help.golden index dcb7c9916e0d4..5e09be061954c 100644 --- a/cli/testdata/coder_state_pull_--help.golden +++ b/cli/testdata/coder_state_pull_--help.golden @@ -3,7 +3,6 @@ Usage: Flags: -b, --build int Specify a workspace build to target by name. - -h, --help help for pull Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_state_push_--help.golden b/cli/testdata/coder_state_push_--help.golden index bb5a2c9a78367..0deb51fcb00cd 100644 --- a/cli/testdata/coder_state_push_--help.golden +++ b/cli/testdata/coder_state_push_--help.golden @@ -3,7 +3,6 @@ Usage: Flags: -b, --build int Specify a workspace build to target by name. - -h, --help help for push Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_stop_--help.golden b/cli/testdata/coder_stop_--help.golden index 63fe36c9d306c..ff41f3a622106 100644 --- a/cli/testdata/coder_stop_--help.golden +++ b/cli/testdata/coder_stop_--help.golden @@ -4,7 +4,6 @@ Usage: coder stop [flags] Flags: - -h, --help help for stop -y, --yes Bypass prompts Global Flags: diff --git a/cli/testdata/coder_templates_--help.golden b/cli/testdata/coder_templates_--help.golden index cdbb0cda2ec15..6f0525d4968cc 100644 --- a/cli/testdata/coder_templates_--help.golden +++ b/cli/testdata/coder_templates_--help.golden @@ -32,8 +32,7 @@ Commands: push Push a new template version from the current directory or as specified by flag versions Manage different versions of the specified template -Flags: - -h, --help help for templates + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_templates_create_--help.golden b/cli/testdata/coder_templates_create_--help.golden index 1e950b50117af..1dbf418831810 100644 --- a/cli/testdata/coder_templates_create_--help.golden +++ b/cli/testdata/coder_templates_create_--help.golden @@ -3,14 +3,15 @@ Create a template from the current directory or as specified by flag Usage: coder templates create [name] [flags] -Flags: +Provisioning Flags: + --provisioner-tag stringArray Specify a set of tags to target provisioner daemons. + +Other Flags: --default-ttl duration Specify a default TTL for workspaces created from this template. (default 24h0m0s) -d, --directory string Specify the directory to create from, use '-' to read tar from stdin (default "[current directory]") - -h, --help help for create --parameter-file string Specify a file path with parameter values. - --provisioner-tag stringArray Specify a set of tags to target provisioner daemons. --variable stringArray Specify a set of values for Terraform-managed variables. --variables-file string Specify a file path with values for Terraform-managed variables. diff --git a/cli/testdata/coder_templates_delete_--help.golden b/cli/testdata/coder_templates_delete_--help.golden index 9284d713bc2d2..3876ab68df434 100644 --- a/cli/testdata/coder_templates_delete_--help.golden +++ b/cli/testdata/coder_templates_delete_--help.golden @@ -4,7 +4,6 @@ Usage: coder templates delete [name...] [flags] Flags: - -h, --help help for delete -y, --yes Bypass prompts Global Flags: diff --git a/cli/testdata/coder_templates_edit_--help.golden b/cli/testdata/coder_templates_edit_--help.golden index f92ba830ad7c6..7ba4ed74bc739 100644 --- a/cli/testdata/coder_templates_edit_--help.golden +++ b/cli/testdata/coder_templates_edit_--help.golden @@ -10,7 +10,6 @@ Flags: workspaces created from this template to this value. --description string Edit the template description --display-name string Edit the template display name - -h, --help help for edit --icon string Edit the template icon path --name string Edit the template name -y, --yes Bypass prompts diff --git a/cli/testdata/coder_templates_init_--help.golden b/cli/testdata/coder_templates_init_--help.golden index 076c5f0951a2f..c21e046a0b99c 100644 --- a/cli/testdata/coder_templates_init_--help.golden +++ b/cli/testdata/coder_templates_init_--help.golden @@ -3,8 +3,7 @@ Get started with a templated template. Usage: coder templates init [directory] [flags] -Flags: - -h, --help help for init + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_templates_list_--help.golden b/cli/testdata/coder_templates_list_--help.golden index 8ac92e6a77330..a08cd6292b9a8 100644 --- a/cli/testdata/coder_templates_list_--help.golden +++ b/cli/testdata/coder_templates_list_--help.golden @@ -10,7 +10,6 @@ Flags: -c, --column strings Columns to display in table output. Available columns: name, created at, last updated, organization id, provisioner, active version id, used by, default ttl (default [name,last updated,used by]) - -h, --help help for list -o, --output string Output format. Available formats: table, json (default "table") Global Flags: diff --git a/cli/testdata/coder_templates_plan_--help.golden b/cli/testdata/coder_templates_plan_--help.golden index fd3ca2e12eb39..f97a7ce6cd021 100644 --- a/cli/testdata/coder_templates_plan_--help.golden +++ b/cli/testdata/coder_templates_plan_--help.golden @@ -3,8 +3,7 @@ Plan a template push from the current directory Usage: coder templates plan [flags] -Flags: - -h, --help help for plan + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_templates_pull_--help.golden b/cli/testdata/coder_templates_pull_--help.golden index af214b70ed954..8a88481f0b436 100644 --- a/cli/testdata/coder_templates_pull_--help.golden +++ b/cli/testdata/coder_templates_pull_--help.golden @@ -4,7 +4,6 @@ Usage: coder templates pull [destination] [flags] Flags: - -h, --help help for pull -y, --yes Bypass prompts Global Flags: diff --git a/cli/testdata/coder_templates_push_--help.golden b/cli/testdata/coder_templates_push_--help.golden index 62c38172a4923..f67dd53924f79 100644 --- a/cli/testdata/coder_templates_push_--help.golden +++ b/cli/testdata/coder_templates_push_--help.golden @@ -3,16 +3,17 @@ Push a new template version from the current directory or as specified by flag Usage: coder templates push [template] [flags] -Flags: +Provisioning Flags: + --provisioner-tag stringArray Specify a set of tags to target provisioner daemons. + +Other Flags: --always-prompt Always prompt all parameters. Does not pull parameter values from active template version -d, --directory string Specify the directory to create from, use '-' to read tar from stdin (default "[current directory]") - -h, --help help for push --name string Specify a name for the new template version. It will be automatically generated if not provided. --parameter-file string Specify a file path with parameter values. - --provisioner-tag stringArray Specify a set of tags to target provisioner daemons. --variable stringArray Specify a set of values for Terraform-managed variables. --variables-file string Specify a file path with values for Terraform-managed variables. diff --git a/cli/testdata/coder_templates_versions_--help.golden b/cli/testdata/coder_templates_versions_--help.golden index b5b345ece283a..4b158aa8c1b5a 100644 --- a/cli/testdata/coder_templates_versions_--help.golden +++ b/cli/testdata/coder_templates_versions_--help.golden @@ -16,8 +16,7 @@ Get Started: Commands: list List all the versions of the specified template -Flags: - -h, --help help for versions + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_templates_versions_list_--help.golden b/cli/testdata/coder_templates_versions_list_--help.golden index a23299869b71b..d79d047986162 100644 --- a/cli/testdata/coder_templates_versions_list_--help.golden +++ b/cli/testdata/coder_templates_versions_list_--help.golden @@ -7,7 +7,6 @@ Flags: -c, --column strings Columns to display in table output. Available columns: name, created at, created by, status, active (default [name,created at,created by,status,active]) - -h, --help help for list -o, --output string Output format. Available formats: table, json (default "table") Global Flags: diff --git a/cli/testdata/coder_tokens_--help.golden b/cli/testdata/coder_tokens_--help.golden index 66b068ebc180b..43063a386eff6 100644 --- a/cli/testdata/coder_tokens_--help.golden +++ b/cli/testdata/coder_tokens_--help.golden @@ -26,8 +26,7 @@ Commands: list List tokens remove Delete a token -Flags: - -h, --help help for tokens + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_tokens_create_--help.golden b/cli/testdata/coder_tokens_create_--help.golden index 22cac73e41b95..3bce1bc1fa4e5 100644 --- a/cli/testdata/coder_tokens_create_--help.golden +++ b/cli/testdata/coder_tokens_create_--help.golden @@ -4,7 +4,6 @@ Usage: coder tokens create [flags] Flags: - -h, --help help for create --lifetime duration Specify a duration for the lifetime of the token. Consumes $CODER_TOKEN_LIFETIME (default 720h0m0s) diff --git a/cli/testdata/coder_tokens_list_--help.golden b/cli/testdata/coder_tokens_list_--help.golden index d9c3acc14b734..83b0b566d8ab3 100644 --- a/cli/testdata/coder_tokens_list_--help.golden +++ b/cli/testdata/coder_tokens_list_--help.golden @@ -9,7 +9,6 @@ Aliases: Flags: -c, --column strings Columns to display in table output. Available columns: id, last used, expires at, created at (default [id,last used,expires at,created at]) - -h, --help help for list -o, --output string Output format. Available formats: table, json (default "table") Global Flags: diff --git a/cli/testdata/coder_tokens_remove_--help.golden b/cli/testdata/coder_tokens_remove_--help.golden index a0d46d2321b67..98957027e3609 100644 --- a/cli/testdata/coder_tokens_remove_--help.golden +++ b/cli/testdata/coder_tokens_remove_--help.golden @@ -6,8 +6,7 @@ Usage: Aliases: remove, rm -Flags: - -h, --help help for remove + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_update_--help.golden b/cli/testdata/coder_update_--help.golden index 85ae220fdd5c1..96aede8511189 100644 --- a/cli/testdata/coder_update_--help.golden +++ b/cli/testdata/coder_update_--help.golden @@ -6,7 +6,6 @@ Usage: Flags: --always-prompt Always prompt all parameters. Does not pull parameter values from existing workspace - -h, --help help for update --parameter-file string Specify a file path with parameter values. Consumes $CODER_PARAMETER_FILE --rich-parameter-file string Specify a file path with values for rich parameters diff --git a/cli/testdata/coder_users_--help.golden b/cli/testdata/coder_users_--help.golden index c9b0b41d27405..c7a94c3f0319c 100644 --- a/cli/testdata/coder_users_--help.golden +++ b/cli/testdata/coder_users_--help.golden @@ -15,8 +15,7 @@ Commands: show Show a single user. Use 'me' to indicate the currently authenticated user. suspend Update a user's status to 'suspended'. A suspended user cannot log into the platform -Flags: - -h, --help help for users + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_users_activate_--help.golden b/cli/testdata/coder_users_activate_--help.golden index 895aeadab5727..60f3015c5a611 100644 --- a/cli/testdata/coder_users_activate_--help.golden +++ b/cli/testdata/coder_users_activate_--help.golden @@ -12,7 +12,6 @@ Get Started: Flags: -c, --column stringArray Specify a column to filter in the table. (default [username,email,created_at,status]) - -h, --help help for activate Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_users_create_--help.golden b/cli/testdata/coder_users_create_--help.golden index ea1af046b1b25..42998d21d5149 100644 --- a/cli/testdata/coder_users_create_--help.golden +++ b/cli/testdata/coder_users_create_--help.golden @@ -3,7 +3,6 @@ Usage: Flags: -e, --email string Specifies an email address for the new user. - -h, --help help for create -p, --password string Specifies a password for the new user. -u, --username string Specifies a username for the new user. diff --git a/cli/testdata/coder_users_list_--help.golden b/cli/testdata/coder_users_list_--help.golden index 71537da026963..acbf4942a8475 100644 --- a/cli/testdata/coder_users_list_--help.golden +++ b/cli/testdata/coder_users_list_--help.golden @@ -7,7 +7,6 @@ Aliases: Flags: -c, --column strings Columns to display in table output. Available columns: id, username, email, created at, status (default [username,email,created_at,status]) - -h, --help help for list -o, --output string Output format. Available formats: table, json (default "table") Global Flags: diff --git a/cli/testdata/coder_users_show_--help.golden b/cli/testdata/coder_users_show_--help.golden index e5945acfad7fe..9d09b3620858b 100644 --- a/cli/testdata/coder_users_show_--help.golden +++ b/cli/testdata/coder_users_show_--help.golden @@ -7,7 +7,6 @@ Get Started: $ coder users show me Flags: - -h, --help help for show -o, --output string Output format. Available formats: table, json (default "table") Global Flags: diff --git a/cli/testdata/coder_users_suspend_--help.golden b/cli/testdata/coder_users_suspend_--help.golden index 3e411849c2bc5..62c9283b1cd42 100644 --- a/cli/testdata/coder_users_suspend_--help.golden +++ b/cli/testdata/coder_users_suspend_--help.golden @@ -12,7 +12,6 @@ Get Started: Flags: -c, --column stringArray Specify a column to filter in the table. (default [username,email,created_at,status]) - -h, --help help for suspend Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/testdata/coder_version_--help.golden b/cli/testdata/coder_version_--help.golden index c560938c09136..b8f80904fb33e 100644 --- a/cli/testdata/coder_version_--help.golden +++ b/cli/testdata/coder_version_--help.golden @@ -3,8 +3,7 @@ Show coder version Usage: coder version [flags] -Flags: - -h, --help help for version + Global Flags: --global-config coder Path to the global coder config directory. diff --git a/cli/usage.go b/cli/usage.go new file mode 100644 index 0000000000000..d71848fced89a --- /dev/null +++ b/cli/usage.go @@ -0,0 +1,297 @@ +package cli + +import ( + "bufio" + "bytes" + "fmt" + "os" + "regexp" + "strings" + "text/template" + + "github.com/creack/pty" + "github.com/spf13/cobra" + + "github.com/coder/coder/cli/cliui" +) + +var templateFunctions = template.FuncMap{ + "usageHeader": usageHeader, + "isWorkspaceCommand": isWorkspaceCommand, + "ttyWidth": ttyWidth, + "categorizeFlags": categorizeFlags, +} + +func usageHeader(s string) string { + // Customizes the color of headings to make subcommands more visually + // appealing. + return cliui.Styles.Placeholder.Render(s) +} + +func isWorkspaceCommand(cmd *cobra.Command) bool { + if _, ok := cmd.Annotations["workspaces"]; ok { + return true + } + var ws bool + cmd.VisitParents(func(cmd *cobra.Command) { + if _, ok := cmd.Annotations["workspaces"]; ok { + ws = true + } + }) + return ws +} + +func ttyWidth() int { + _, cols, err := pty.Getsize(os.Stderr) + if err != nil { + // Default width + return 100 + } + return cols +} + +type flagCategory struct { + name string + matchers []*regexp.Regexp +} + +// flagCategories are evaluated by categorizeFlags in order. Evaluation ends +// once the first category is matched. +var flagCategories = []flagCategory{ + { + name: "Networking", + matchers: []*regexp.Regexp{ + regexp.MustCompile("-derp"), + regexp.MustCompile("-access-url"), + regexp.MustCompile("-http-address"), + regexp.MustCompile("-proxy"), + regexp.MustCompile("-auth-cookie"), + regexp.MustCompile("-strict-transport"), + regexp.MustCompile("-tls"), + // NOT open-telemetry + regexp.MustCompile("--telemetry"), + regexp.MustCompile("-update-check"), + }, + }, + { + name: "Auth", + matchers: []*regexp.Regexp{ + regexp.MustCompile(`-\w*auth`), + regexp.MustCompile("oidc"), + regexp.MustCompile(`-\w*token`), + regexp.MustCompile("session"), + }, + }, + { + name: "Operability", + matchers: []*regexp.Regexp{ + regexp.MustCompile("--log"), + regexp.MustCompile("pprof"), + regexp.MustCompile("prometheus"), + regexp.MustCompile("trace"), + }, + }, + { + name: "Provisioning", + matchers: []*regexp.Regexp{ + regexp.MustCompile("--provisioner"), + }, + }, + { + name: "Other", + matchers: []*regexp.Regexp{ + // Everything! + regexp.MustCompile("."), + }, + }, +} + +// categorizeFlags makes the `coder server --help` output bearable by grouping +// similar flags. This approach is janky, but the alternative is reimplementing +// https://github.com/spf13/pflag/blob/v1.0.5/flag.go#L677, which involves +// hundreds of lines of complex code since key functions are internal. +func categorizeFlags(usageOutput string) string { + var out strings.Builder + + var ( + sc = bufio.NewScanner(strings.NewReader(usageOutput)) + currentFlag bytes.Buffer + categories = make(map[string]*bytes.Buffer) + ) + flushCurrentFlag := func() { + defer currentFlag.Reset() + + if currentFlag.Len() == 0 { + return + } + + // Help is a bit redundant. + if strings.Contains(currentFlag.String(), "-h, --help") { + return + } + + for _, cat := range flagCategories { + for _, matcher := range cat.matchers { + if !matcher.MatchString(currentFlag.String()) { + continue + } + + catBuf, ok := categories[cat.name] + if !ok { + catBuf = &bytes.Buffer{} + categories[cat.name] = catBuf + } + + if os.Getenv("DEBUG_FLAG_CATEGORIZATION") != "" { + _, _ = os.Stderr.WriteString( + fmt.Sprintf( + "--- \n%s\nwas matched by `%s`\n---\n", + currentFlag.String(), matcher.String(), + ), + ) + } + + _, _ = currentFlag.WriteTo(catBuf) + return + } + } + + _, _ = out.WriteString("ERROR: no category matched for flag\n") + _, _ = currentFlag.WriteTo(&out) + } + for sc.Scan() { + if strings.HasPrefix(strings.TrimSpace(sc.Text()), "-") { + // Beginning of a new flag, flush old. + flushCurrentFlag() + } + _, _ = currentFlag.WriteString(sc.Text()) + _ = currentFlag.WriteByte('\n') + } + flushCurrentFlag() + + var prevBody string + + for _, cat := range flagCategories { + buf, ok := categories[cat.name] + if !ok { + continue + } + + // If the last line of the previous category is a single-line flag, + // then it isn't indented, and an additional newline is necessary to + // make the output readable. + if prevBody != "" { + prevBodyLines := strings.Split(strings.TrimSpace(prevBody), "\n") + if len(prevBodyLines) > 0 { + lastLine := prevBodyLines[len(prevBodyLines)-1] + if strings.HasPrefix(strings.TrimSpace(lastLine), "-") { + _, _ = out.WriteString("\n") + } + } + } + + if len(categories) == 1 { + // Don't bother qualifying list name if there's only one category. + _, _ = fmt.Fprintf(&out, "%s\n", usageHeader("Flags:")) + } else { + _, _ = fmt.Fprintf(&out, "%s\n", usageHeader(cat.name+" Flags:")) + } + + body := buf.String() + _, _ = out.WriteString(body) + prevBody = body + } + + return out.String() +} + +func usageTemplate() string { + // usageHeader is defined in init(). + return `{{usageHeader "Usage:"}} +{{- if .Runnable}} + {{.UseLine}} +{{end}} +{{- if .HasAvailableSubCommands}} + {{.CommandPath}} [command] +{{end}} + +{{- if gt (len .Aliases) 0}} +{{usageHeader "Aliases:"}} + {{.NameAndAliases}} +{{end}} + +{{- if .HasExample}} +{{usageHeader "Get Started:"}} +{{.Example}} +{{end}} + +{{- $isRootHelp := (not .HasParent)}} +{{- if .HasAvailableSubCommands}} +{{usageHeader "Commands:"}} + {{- range .Commands}} + {{- $isRootWorkspaceCommand := (and $isRootHelp (isWorkspaceCommand .))}} + {{- if (or (and .IsAvailableCommand (not $isRootWorkspaceCommand)) (eq .Name "help"))}} + {{rpad .Name .NamePadding }} {{.Short}} + {{- end}} + {{- end}} +{{end}} + +{{- if (and $isRootHelp .HasAvailableSubCommands)}} +{{usageHeader "Workspace Commands:"}} + {{- range .Commands}} + {{- if (and .IsAvailableCommand (isWorkspaceCommand .))}} + {{rpad .Name .NamePadding }} {{.Short}} + {{- end}} + {{- end}} +{{end}} + +{{- if .HasAvailableLocalFlags}} +{{.LocalFlags.FlagUsagesWrapped ttyWidth | categorizeFlags | trimTrailingWhitespaces}} +{{end}} + +{{- if .HasAvailableInheritedFlags}} +{{usageHeader "Global Flags:"}} +{{.InheritedFlags.FlagUsagesWrapped ttyWidth | trimTrailingWhitespaces}} +{{end}} + +{{- if .HasHelpSubCommands}} +{{usageHeader "Additional help topics:"}} + {{- range .Commands}} + {{- if .IsAdditionalHelpTopicCommand}} + {{rpad .CommandPath .CommandPathPadding}} {{.Short}} + {{- end}} + {{- end}} +{{end}} + +{{- if .HasAvailableSubCommands}} +Use "{{.CommandPath}} [command] --help" for more information about a command. +{{end}}` +} + +// example represents a standard example for command usage, to be used +// with formatExamples. +type example struct { + Description string + Command string +} + +// formatExamples formats the examples as width wrapped bulletpoint +// descriptions with the command underneath. +func formatExamples(examples ...example) string { + wrap := cliui.Styles.Wrap.Copy() + wrap.PaddingLeft(4) + var sb strings.Builder + for i, e := range examples { + if len(e.Description) > 0 { + _, _ = sb.WriteString(" - " + wrap.Render(e.Description + ":")[4:] + "\n\n ") + } + // We add 1 space here because `cliui.Styles.Code` adds an extra + // space. This makes the code block align at an even 2 or 6 + // spaces for symmetry. + _, _ = sb.WriteString(" " + cliui.Styles.Code.Render(fmt.Sprintf("$ %s", e.Command))) + if i < len(examples)-1 { + _, _ = sb.WriteString("\n\n") + } + } + return sb.String() +} diff --git a/docs/cli/coder_server.md b/docs/cli/coder_server.md index fd844729734e4..4cf3e5cb614f5 100644 --- a/docs/cli/coder_server.md +++ b/docs/cli/coder_server.md @@ -11,16 +11,8 @@ coder server [flags] ``` --access-url string External URL to access your deployment. This must be accessible by all provisioned workspaces. Consumes $CODER_ACCESS_URL - --api-rate-limit int Maximum number of requests per minute allowed to the API per user, or per IP address for unauthenticated users. Negative values mean no rate limit. Some API endpoints have separate strict rate limits regardless of this value to prevent denial-of-service or brute force attacks. - Consumes $CODER_API_RATE_LIMIT (default 512) --cache-dir string The directory to cache temporary files. If unspecified and $CACHE_DIRECTORY is set, it will be used for compatibility with systemd. Consumes $CODER_CACHE_DIRECTORY (default "~/.cache/coder") - --dangerous-allow-path-app-sharing Allow workspace apps that are not served from subdomains to be shared. Path-based app sharing is DISABLED by default for security purposes. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security. - Consumes $CODER_DANGEROUS_ALLOW_PATH_APP_SHARING - --dangerous-allow-path-app-site-owner-access Allow site-owners to access workspace apps from workspaces they do not own. Owners cannot access path-based apps they do not own by default. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security. - Consumes $CODER_DANGEROUS_ALLOW_PATH_APP_SITE_OWNER_ACCESS - --dangerous-disable-rate-limits Disables all rate limits. This is not recommended in production. - Consumes $CODER_RATE_LIMIT_DISABLE_ALL --derp-config-path string Path to read a DERP mapping from. See: https://tailscale.com/kb/1118/custom-derp-servers/ Consumes $CODER_DERP_CONFIG_PATH --derp-config-url string URL to fetch a DERP mapping on startup. See: https://tailscale.com/kb/1118/custom-derp-servers/