@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -89,7 +89,7 @@ jobs:
 
       - name: Log in to Docker Hub
         if: inputs.publish
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
 
@@ -16,10 +16,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: go.mod
 
@@ -53,12 +53,12 @@ jobs:
       HAS_SECRETS: ${{ secrets.TEMPORAL_CLIENT_CERT != '' && secrets.TEMPORAL_CLIENT_KEY != '' }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 
       - name: Setup Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: go.mod
 
@@ -69,7 +69,13 @@ jobs:
         run: mkdir junit-xml
 
       - name: Test
-        run: gotestsum --junitfile junit-xml/${{matrix.os}}.xml -- ./...
+        shell: bash
+        run: |
+          gotestsum --junitfile junit-xml/${{matrix.os}}.xml -- ./...
+          (
+            cd cliext
+            gotestsum --junitfile ../junit-xml/${{matrix.os}}-cliext.xml -- ./...
+          )
 
       - name: Upload junit-xml artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
 
@@ -11,8 +11,8 @@ jobs:
     name: Govulncheck
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: go.mod
       - uses: temporalio/public-actions/golang/govulncheck@main
@@ -15,12 +15,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
       - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: "go.mod"
           check-latest: true
 
@@ -17,9 +17,9 @@ jobs:
     name: Validate Dependabot Config
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.12'
 
 
@@ -23,3 +23,7 @@ gen-docs: internal/temporalcli/commands.yaml cliext/option-sets.yaml
 
 build:
 	go build ./cmd/temporal
+
+test:
+	(cd cliext && go test ./...)
+	go test ./...
@@ -30,14 +30,18 @@ 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.")
 	v.LogFormat = NewFlagStringEnum([]string{"text", "json", "pretty"}, "text")
@@ -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 {
@@ -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
 }
@@ -1,38 +1,40 @@
 module github.com/temporalio/cli/cliext
 
-go 1.25.0
+go 1.26.4
 
 require (
 	github.com/BurntSushi/toml v1.4.0
-	github.com/mattn/go-isatty v0.0.20
+	github.com/mattn/go-isatty v0.0.23
 	github.com/spf13/pflag v1.0.10
-	github.com/stretchr/testify v1.10.0
-	go.temporal.io/sdk v1.41.0
+	github.com/stretchr/testify v1.11.1
+	go.temporal.io/sdk v1.41.1
 	go.temporal.io/sdk/contrib/envconfig v1.0.0
-	golang.org/x/oauth2 v0.34.0
-	google.golang.org/grpc v1.79.3
+	golang.org/x/oauth2 v0.36.0
+	google.golang.org/grpc v1.82.1
 )
 
 require (
-	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/facebookgo/clock v0.0.0-20150410010913-600d898af40a // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/golang/mock v1.6.0 // indirect
+	github.com/golang/mock v1.7.0-rc.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect
-	github.com/grpc-ecosystem/go-grpc-middleware/v2 v2.3.2 // indirect
-	github.com/grpc-ecosystem/grpc-gateway/v2 v2.22.0 // indirect
+	github.com/grpc-ecosystem/go-grpc-middleware/v2 v2.3.3 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 // indirect
 	github.com/nexus-rpc/sdk-go v0.6.0 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/robfig/cron v1.2.0 // indirect
-	github.com/stretchr/objx v0.5.2 // indirect
-	go.temporal.io/api v1.62.2 // indirect
-	golang.org/x/net v0.48.0 // indirect
-	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.39.0 // indirect
-	golang.org/x/text v0.32.0 // indirect
-	golang.org/x/time v0.3.0 // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20251202230838-ff82c1b0f217 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217 // indirect
-	google.golang.org/protobuf v1.36.10 // indirect
+	github.com/rogpeppe/go-internal v1.14.1 // indirect
+	github.com/stretchr/objx v0.5.3 // indirect
+	go.opentelemetry.io/otel v1.44.0 // indirect
+	go.temporal.io/api v1.62.9 // indirect
+	golang.org/x/net v0.57.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
+	golang.org/x/time v0.15.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260420184626-e10c466a9529 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260420184626-e10c466a9529 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )