Skip to content

feat: add temporal options command and declutter help output #1061

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
chaptersix wants to merge 1 commit into
base: main
Choose a base branch
from
+268 −90
Draft

feat: add temporal options command and declutter help output #1061

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 58 additions & 26 deletions cliext/flags.gen.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,16 +30,20 @@ type CommonOptions struct {
FlagSet *pflag.FlagSet
}

func (v *CommonOptions) Description() string {
return "These options apply to every command. They control output formatting,\nlogging, and which configuration profile and environment to use.\nOptions that accept an environment variable can be set instead of\npassing the flag each time.\n"
}

func (v *CommonOptions) BuildFlags(f *pflag.FlagSet) {
v.FlagSet = f
f.StringVar(&v.Env, "env", "default", "Active environment name (`ENV`).")
f.StringVar(&v.EnvFile, "env-file", "", "Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.")
f.StringVar(&v.ConfigFile, "config-file", "", "File path to read TOML config from, defaults to `$CONFIG_PATH/temporalio/temporal.toml` where `$CONFIG_PATH` is defined as `$HOME/.config` on Unix, `$HOME/Library/Application Support` on macOS, and `%AppData%` on Windows.")
f.StringVar(&v.Profile, "profile", "", "Profile to use for config file.")
f.BoolVar(&v.DisableConfigFile, "disable-config-file", false, "If set, disables loading environment config from config file.")
f.BoolVar(&v.DisableConfigEnv, "disable-config-env", false, "If set, disables loading environment config from environment variables.")
f.StringVar(&v.Env, "env", "default", "Active environment name (`ENV`). Env: TEMPORAL_ENV.")
f.StringVar(&v.EnvFile, "env-file", "", "Path to environment settings file. Env: TEMPORAL_ENV_FILE.")
f.StringVar(&v.ConfigFile, "config-file", "", "TOML config file path. Env: TEMPORAL_CONFIG_FILE.")
f.StringVar(&v.Profile, "profile", "", "Profile to use for config file. Env: TEMPORAL_PROFILE.")
f.BoolVar(&v.DisableConfigFile, "disable-config-file", false, "Disable loading config from file.")
f.BoolVar(&v.DisableConfigEnv, "disable-config-env", false, "Disable loading config from environment variables.")
v.LogLevel = NewFlagStringEnum([]string{"debug", "info", "warn", "error", "never"}, "never")
f.Var(&v.LogLevel, "log-level", "Log level. Default is \"never\" for most commands and \"warn\" for \"server start-dev\". Accepted values: debug, info, warn, error, never.")
f.Var(&v.LogLevel, "log-level", "Log level. Accepted values: debug, info, warn, error, never.")
v.LogFormat = NewFlagStringEnum([]string{"text", "json", "pretty"}, "text")
f.Var(&v.LogFormat, "log-format", "Log format. Accepted values: text, json.")
v.Output = NewFlagStringEnum([]string{"text", "json", "jsonl", "none"}, "text")
Expand All @@ -50,9 +54,9 @@ func (v *CommonOptions) BuildFlags(f *pflag.FlagSet) {
f.Var(&v.Color, "color", "Output coloring. Accepted values: always, never, auto.")
f.BoolVar(&v.NoJsonShorthandPayloads, "no-json-shorthand-payloads", false, "Raw payload output, even if the JSON option was used.")
v.CommandTimeout = 0
f.Var(&v.CommandTimeout, "command-timeout", "The command execution timeout. 0s means no timeout.")
f.Var(&v.CommandTimeout, "command-timeout", "Command execution timeout.")
v.ClientConnectTimeout = 0
f.Var(&v.ClientConnectTimeout, "client-connect-timeout", "The client connection timeout. 0s means no timeout.")
f.Var(&v.ClientConnectTimeout, "client-connect-timeout", "Client connection timeout.")
}

type ClientOptions struct {
Expand All @@ -77,24 +81,52 @@ type ClientOptions struct {
FlagSet *pflag.FlagSet
}

func (v *ClientOptions) Description() string {
return "These options apply to commands that connect to a Temporal Service\n(workflow, activity, schedule, etc). They specify the server address,\nnamespace, authentication, and TLS settings. Values are resolved in\norder: CLI flag > environment variable > config file.\n\nTo persist these settings, use:\n temporal config set --prop KEY --value VALUE\n"
}

func (v *ClientOptions) BuildFlags(f *pflag.FlagSet) {
v.FlagSet = f
f.StringVar(&v.Address, "address", "localhost:7233", "Temporal Service gRPC endpoint.")
f.StringVar(&v.Address, "address", "localhost:7233", "Temporal Service gRPC endpoint. Env: TEMPORAL_ADDRESS. Config: address.")
f.StringVar(&v.ClientAuthority, "client-authority", "", "Temporal gRPC client :authority pseudoheader.")
f.StringVarP(&v.Namespace, "namespace", "n", "default", "Temporal Service Namespace.")
f.StringVar(&v.ApiKey, "api-key", "", "API key for request.")
f.StringArrayVar(&v.GrpcMeta, "grpc-meta", nil, "HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.")
f.BoolVar(&v.Tls, "tls", false, "Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.")
f.StringVar(&v.TlsCertPath, "tls-cert-path", "", "Path to x509 certificate. Can't be used with --tls-cert-data.")
f.StringVar(&v.TlsCertData, "tls-cert-data", "", "Data for x509 certificate. Can't be used with --tls-cert-path.")
f.StringVar(&v.TlsKeyPath, "tls-key-path", "", "Path to x509 private key. Can't be used with --tls-key-data.")
f.StringVar(&v.TlsKeyData, "tls-key-data", "", "Private certificate key data. Can't be used with --tls-key-path.")
f.StringVar(&v.TlsCaPath, "tls-ca-path", "", "Path to server CA certificate. Can't be used with --tls-ca-data.")
f.StringVar(&v.TlsCaData, "tls-ca-data", "", "Data for server CA certificate. Can't be used with --tls-ca-path.")
f.BoolVar(&v.TlsDisableHostVerification, "tls-disable-host-verification", false, "Disable TLS host-name verification.")
f.StringVar(&v.TlsServerName, "tls-server-name", "", "Override target TLS server name.")
f.StringVar(&v.CodecEndpoint, "codec-endpoint", "", "Remote Codec Server endpoint.")
f.StringVar(&v.CodecAuth, "codec-auth", "", "Authorization header for Codec Server requests.")
f.StringArrayVar(&v.CodecHeader, "codec-header", nil, "HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.")
f.StringVar(&v.Identity, "identity", "", "The identity of the user or client submitting this request. Defaults to \"temporal-cli:$USER@$HOST\".")
f.StringVarP(&v.Namespace, "namespace", "n", "default", "Temporal Service Namespace. Env: TEMPORAL_NAMESPACE. Config: namespace.")
f.StringVar(&v.ApiKey, "api-key", "", "API key for request. Env: TEMPORAL_API_KEY. Config: api_key.")
f.StringArrayVar(&v.GrpcMeta, "grpc-meta", nil, "HTTP headers for requests (KEY=VALUE, repeatable). Config: grpc_meta.<key>.")
f.BoolVar(&v.Tls, "tls", false, "Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. Env: TEMPORAL_TLS. Config: tls.")
f.StringVar(&v.TlsCertPath, "tls-cert-path", "", "Path to x509 certificate. Env: TEMPORAL_TLS_CLIENT_CERT_PATH. Config: tls.client_cert_path.")
f.StringVar(&v.TlsCertData, "tls-cert-data", "", "Inline x509 certificate data. Env: TEMPORAL_TLS_CLIENT_CERT_DATA. Config: tls.client_cert_data.")
f.StringVar(&v.TlsKeyPath, "tls-key-path", "", "Path to x509 private key. Env: TEMPORAL_TLS_CLIENT_KEY_PATH. Config: tls.client_key_path.")
f.StringVar(&v.TlsKeyData, "tls-key-data", "", "Inline x509 private key data. Env: TEMPORAL_TLS_CLIENT_KEY_DATA. Config: tls.client_key_data.")
f.StringVar(&v.TlsCaPath, "tls-ca-path", "", "Path to server CA certificate. Env: TEMPORAL_TLS_SERVER_CA_CERT_PATH. Config: tls.server_ca_cert_path.")
f.StringVar(&v.TlsCaData, "tls-ca-data", "", "Inline server CA certificate data. Env: TEMPORAL_TLS_SERVER_CA_CERT_DATA. Config: tls.server_ca_cert_data.")
f.BoolVar(&v.TlsDisableHostVerification, "tls-disable-host-verification", false, "Disable TLS host-name verification. Env: TEMPORAL_TLS_DISABLE_HOST_VERIFICATION. Config: tls.disable_host_verification.")
f.StringVar(&v.TlsServerName, "tls-server-name", "", "Override target TLS server name. Env: TEMPORAL_TLS_SERVER_NAME. Config: tls.server_name.")
f.StringVar(&v.CodecEndpoint, "codec-endpoint", "", "Remote Codec Server endpoint. Env: TEMPORAL_CODEC_ENDPOINT. Config: codec.endpoint.")
f.StringVar(&v.CodecAuth, "codec-auth", "", "Authorization header for Codec Server requests. Env: TEMPORAL_CODEC_AUTH. Config: codec.auth.")
f.StringArrayVar(&v.CodecHeader, "codec-header", nil, "HTTP headers for codec server (KEY=VALUE, repeatable).")
f.StringVar(&v.Identity, "identity", "", "Identity of the client submitting requests.")
}

func (v *ClientOptions) HideFlags() {
if v.FlagSet == nil {
return
}
v.FlagSet.Lookup("address").Hidden = true
v.FlagSet.Lookup("client-authority").Hidden = true
v.FlagSet.Lookup("namespace").Hidden = true
v.FlagSet.Lookup("api-key").Hidden = true
v.FlagSet.Lookup("grpc-meta").Hidden = true
v.FlagSet.Lookup("tls").Hidden = true
v.FlagSet.Lookup("tls-cert-path").Hidden = true
v.FlagSet.Lookup("tls-cert-data").Hidden = true
v.FlagSet.Lookup("tls-key-path").Hidden = true
v.FlagSet.Lookup("tls-key-data").Hidden = true
v.FlagSet.Lookup("tls-ca-path").Hidden = true
v.FlagSet.Lookup("tls-ca-data").Hidden = true
v.FlagSet.Lookup("tls-disable-host-verification").Hidden = true
v.FlagSet.Lookup("tls-server-name").Hidden = true
v.FlagSet.Lookup("codec-endpoint").Hidden = true
v.FlagSet.Lookup("codec-auth").Hidden = true
v.FlagSet.Lookup("codec-header").Hidden = true
v.FlagSet.Lookup("identity").Hidden = true
}
99 changes: 46 additions & 53 deletions cliext/option-sets.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@

option-sets:
- name: common
description: |
These options apply to every command. They control output formatting,
logging, and which configuration profile and environment to use.
Options that accept an environment variable can be set instead of
passing the flag each time.
options:
- name: env
type: string
Expand All @@ -12,31 +17,22 @@ option-sets:
implied-env: TEMPORAL_ENV
- name: env-file
type: string
description: |
Path to environment settings file.
Defaults to `$HOME/.config/temporalio/temporal.yaml`.
description: Path to environment settings file.
implied-env: TEMPORAL_ENV_FILE
- name: config-file
type: string
description: |
File path to read TOML config from, defaults to
`$CONFIG_PATH/temporalio/temporal.toml` where `$CONFIG_PATH` is defined
as `$HOME/.config` on Unix, `$HOME/Library/Application Support` on
macOS, and `%AppData%` on Windows.
description: TOML config file path.
implied-env: TEMPORAL_CONFIG_FILE
- name: profile
type: string
description: Profile to use for config file.
implied-env: TEMPORAL_PROFILE
- name: disable-config-file
type: bool
description: |
If set, disables loading environment config from config file.
description: Disable loading config from file.
- name: disable-config-env
type: bool
description: |
If set, disables loading environment config from environment
variables.
description: Disable loading config from environment variables.
- name: log-level
type: string-enum
enum-values:
Expand All @@ -45,9 +41,7 @@ option-sets:
- warn
- error
- never
description: |
Log level.
Default is "never" for most commands and "warn" for "server start-dev".
description: Log level.
default: never
- name: log-format
type: string-enum
Expand Down Expand Up @@ -89,20 +83,28 @@ option-sets:
description: Raw payload output, even if the JSON option was used.
- name: command-timeout
type: duration
description: |
The command execution timeout. 0s means no timeout.
description: Command execution timeout.
- name: client-connect-timeout
type: duration
description: |
The client connection timeout. 0s means no timeout.
description: Client connection timeout.

- name: client
hide-from-help: true
description: |
These options apply to commands that connect to a Temporal Service
(workflow, activity, schedule, etc). They specify the server address,
namespace, authentication, and TLS settings. Values are resolved in
order: CLI flag > environment variable > config file.

To persist these settings, use:
temporal config set --prop KEY --value VALUE
options:
- name: address
type: string
description: Temporal Service gRPC endpoint.
default: localhost:7233
implied-env: TEMPORAL_ADDRESS
config-key: address
- name: client-authority
type: string
description: Temporal gRPC client :authority pseudoheader.
Expand All @@ -112,83 +114,74 @@ option-sets:
description: Temporal Service Namespace.
default: default
implied-env: TEMPORAL_NAMESPACE
config-key: namespace
- name: api-key
type: string
description: API key for request.
implied-env: TEMPORAL_API_KEY
config-key: api_key
- name: grpc-meta
type: string[]
description: |
HTTP headers for requests.
Format as a `KEY=VALUE` pair.
May be passed multiple times to set multiple headers.
Can also be made available via environment variable as
`TEMPORAL_GRPC_META_[name]`.
description: HTTP headers for requests (KEY=VALUE, repeatable).
config-key: grpc_meta.<key>
- name: tls
type: bool
description: |
Enable base TLS encryption. Does not have additional options like mTLS
or client certs. This is defaulted to true if api-key or any other TLS
options are present. Use --tls=false to explicitly disable.
description: Enable base TLS encryption. Auto-enabled when api-key or TLS options are set.
implied-env: TEMPORAL_TLS
config-key: tls
- name: tls-cert-path
type: string
description: |
Path to x509 certificate.
Can't be used with --tls-cert-data.
description: Path to x509 certificate.
implied-env: TEMPORAL_TLS_CLIENT_CERT_PATH
config-key: tls.client_cert_path
- name: tls-cert-data
type: string
description: |
Data for x509 certificate.
Can't be used with --tls-cert-path.
description: Inline x509 certificate data.
implied-env: TEMPORAL_TLS_CLIENT_CERT_DATA
config-key: tls.client_cert_data
- name: tls-key-path
type: string
description: |
Path to x509 private key.
Can't be used with --tls-key-data.
description: Path to x509 private key.
implied-env: TEMPORAL_TLS_CLIENT_KEY_PATH
config-key: tls.client_key_path
- name: tls-key-data
type: string
description: |
Private certificate key data.
Can't be used with --tls-key-path.
description: Inline x509 private key data.
implied-env: TEMPORAL_TLS_CLIENT_KEY_DATA
config-key: tls.client_key_data
- name: tls-ca-path
type: string
description: |
Path to server CA certificate.
Can't be used with --tls-ca-data.
description: Path to server CA certificate.
implied-env: TEMPORAL_TLS_SERVER_CA_CERT_PATH
config-key: tls.server_ca_cert_path
- name: tls-ca-data
type: string
description: |
Data for server CA certificate.
Can't be used with --tls-ca-path.
description: Inline server CA certificate data.
implied-env: TEMPORAL_TLS_SERVER_CA_CERT_DATA
config-key: tls.server_ca_cert_data
- name: tls-disable-host-verification
type: bool
description: Disable TLS host-name verification.
implied-env: TEMPORAL_TLS_DISABLE_HOST_VERIFICATION
config-key: tls.disable_host_verification
- name: tls-server-name
type: string
description: Override target TLS server name.
implied-env: TEMPORAL_TLS_SERVER_NAME
config-key: tls.server_name
- name: codec-endpoint
type: string
description: Remote Codec Server endpoint.
implied-env: TEMPORAL_CODEC_ENDPOINT
config-key: codec.endpoint
- name: codec-auth
type: string
description: Authorization header for Codec Server requests.
implied-env: TEMPORAL_CODEC_AUTH
config-key: codec.auth
- name: codec-header
type: string[]
description: |
HTTP headers for requests to codec server.
Format as a `KEY=VALUE` pair.
May be passed multiple times to set multiple headers.
description: HTTP headers for codec server (KEY=VALUE, repeatable).
- name: identity
type: string
description: The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".
description: Identity of the client submitting requests.
30 changes: 29 additions & 1 deletion internal/commandsgen/code.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,13 +143,29 @@ func (o *OptionSets) writeCode(w *codeWriter) error {
w.writeLinef("FlagSet *%v.FlagSet", w.importPflag())
w.writeLinef("}\n")

// write description if present
if o.Description != "" {
w.writeLinef("func (v *%v) Description() string { return %q }", o.setStructName(), o.Description)
w.writeLinef("")
}

// write flags
w.writeLinef("func (v *%v) BuildFlags(f *%v.FlagSet) {",
o.setStructName(), w.importPflag())
w.writeLinef("v.FlagSet = f")
o.writeFlagBuilding("v", "f", w)
w.writeLinef("}\n")

// write HideFlags if hide-from-help is set
if o.HideFromHelp {
w.writeLinef("func (v *%v) HideFlags() {", o.setStructName())
w.writeLinef("if v.FlagSet == nil { return }")
for _, opt := range o.Options {
w.writeLinef("v.FlagSet.Lookup(%q).Hidden = true", opt.Name)
}
w.writeLinef("}\n")
}

return nil
}

Expand Down Expand Up @@ -275,9 +291,15 @@ func (c *Command) writeCode(w *codeWriter) error {
if optSet != nil && optSet.ExternalPackage != "" {
// External option-set: use type name with Options suffix
w.writeLinef("s.%vOptions.BuildFlags(%v)", namify(include, true), flagVar)
if optSet.HideFromHelp {
w.writeLinef("s.%vOptions.HideFlags()", namify(include, true))
}
} else {
// Internal option-set: use struct name
w.writeLinef("s.%v.BuildFlags(%v)", setStructName(include), flagVar)
if optSet != nil && optSet.HideFromHelp {
w.writeLinef("s.%v.HideFlags()", setStructName(include))
}
}
}

Expand Down Expand Up @@ -422,8 +444,14 @@ func (o *Option) writeFlagBuilding(selfVar, flagVar string, w *codeWriter) error
return fmt.Errorf("unrecognized data type %v", o.Type)
}

// If there are enums, append to desc
// If there is an implied env var or config key, append to desc
desc := o.Description
if o.ImpliedEnv != "" {
desc += fmt.Sprintf(" Env: %s.", o.ImpliedEnv)
}
if o.ConfigKey != "" {
desc += fmt.Sprintf(" Config: %s.", o.ConfigKey)
}
if len(o.EnumValues) > 0 {
desc += fmt.Sprintf(" Accepted values: %s.", strings.Join(o.EnumValues, ", "))
}
Expand Down
2 changes: 2 additions & 0 deletions internal/commandsgen/parse.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ type (
Short string `yaml:"short,omitempty"`
Default string `yaml:"default,omitempty"`
ImpliedEnv string `yaml:"implied-env,omitempty"`
ConfigKey string `yaml:"config-key,omitempty"`
Required bool `yaml:"required,omitempty"`
Aliases []string `yaml:"aliases,omitempty"`
EnumValues []string `yaml:"enum-values,omitempty"`
Expand Down Expand Up @@ -63,6 +64,7 @@ type (
Description string `yaml:"description"`
Options []Option `yaml:"options"`
ExternalPackage string `yaml:"external-package"`
HideFromHelp bool `yaml:"hide-from-help,omitempty"`
}

// Commands represents the top-level structure holding commands and option sets.
Expand Down
Loading
Loading