feat: add temporal options command and declutter help output - #1061
Merged
Conversation
Hide global and connection flags from help output, replacing them with a hint to the new `temporal options` command. This follows the kubectl pattern where `kubectl options` lists global flags. Changes: - Add `temporal options` command with grouped tables for global and connection options, showing flag, env var, config key, and description - Hide root persistent flags from root help output - Hide client option flags from subcommand help via `hide-from-help` option set attribute and generated `HideFlags()` methods - Add `implied-env` and `config-key` annotations to generated flag descriptions so env vars and config keys are discoverable - Add `Description()` methods to option sets, driven from YAML - Shorten option descriptions to remove info now shown in table columns
harani-mukkala
approved these changes
Jun 1, 2026
chaptersix
marked this pull request as ready for review
July 23, 2026 15:20
Contributor
Author
|
if it's not already, make this experimental. we'll iterate on it. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f17d16e4c6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| // 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) |
There was a problem hiding this comment.
This now appends every implied-env to user-facing help, which makes --env-file show Env: TEMPORAL_ENV_FILE, but that variable is never consumed when selecting the deprecated env config file: preprocessOptions only prefetches --env-file from Args and otherwise falls back to the default path, and a repo-wide search shows no TEMPORAL_ENV_FILE lookup. Users following temporal options will set this env var and still have the CLI read the default env file, potentially using the wrong saved environment.
Useful? React with 👍 / 👎.
Contributor
Author
|
Since the last review, I added two root-help examples to improve discoverability:
The root-help test covers both examples. |
ks-temporal
added a commit
that referenced
this pull request
Sep 1, 2026
# Backport for CLI v1.8.3 (monthly public/latest) Cuts the scheduled monthly public/latest release onto `release/1.8.x`, which was sitting exactly on `v1.8.2` with nothing backported since 2026-07-31. **The governing constraint:** this release keeps the embedded dev server on OSS Server **v1.31.2**. Everything below follows from that. `main` has moved to server `v1.32.0-162.0` (a Cloud tag) and `go.temporal.io/api` v1.63.x, so `main` is not publicly releasable and a large share of recent work cannot ship here. ## Summary Of the 29 commits on `main` since `v1.8.2`: | | Count | |---|---| | Cherry-picked as-is | 13 | | Dependency bumps folded into one commit | 5 | | New commits authored for this backport | 2 | | Excluded | 11 | Verified: `go build ./...` and `cliext` build clean, `make gen` produces no diff, full `go test ./...` green, binary reports `Server 1.31.2, UI 2.50.1`. ## Included ### Cherry-picked from `main` | Commit | Change | |---|---| | #1153 | test: fix concurrent start test assertions | | #1140 | Gate AWS Lambda role/external-id behind `--aws-lambda-skip-role-and-external-id` | | #1137 | Delegate help and completion to extensions when applicable | | #1167 | Add `--gcp-cloud-run-scale-down-stabilization-duration` | | #1176 | Fix cliext build, add it to CI workflow | | #1149 | chore(deps): bump the github-actions group with 3 updates | | #1162 | chore(deps): bump docker/login-action 4.4.0 → 4.5.2 | | #1166 | chore(deps): bump docker/login-action 4.5.2 → 4.6.0 | | #1156 | fix(activity): remove no-op `reset-attempts` flag — **adjusted, see below** | | #1061 | feat: add `temporal options` command and declutter help output | | #1171 | test: stabilize activity list pagination | | #1186 | fix: document `start-dev` `--log-level` default | | #1177 | Support AWS AgentCore compute provider | The last three merged to `main` on 2026-09-01, after the initial backport set was assembled, and all three cherry-pick cleanly with no dependency movement. **#1177 (AgentCore)** is a new feature rather than a fix, so it warrants a deliberate look. It carries no api v1.63.x dependency: the provider type is the plain string `"aws-agentcore"` and the provider details are an opaque `map[string]any` encoded to a `commonpb.Payload`. Server v1.31.2 does not validate the provider type — it forwards it as `wciiface.ComputeProviderType` — so acceptance is decided by Cloud-side WCI, not by anything this release pins. Its functional test is `t.Skip`-ed pending AWS fixtures, which matches the existing Lambda and GCP Cloud Run compute-provider tests. **#1171** needed one addition on this line: its new `TestActivity_List_Pagination` calls `activity.GetInfo(ctx)`, and the `go.temporal.io/sdk/activity` import is present on `main` but not in this file on `release/1.8.x`. The import is folded into the #1171 pick so each commit builds standalone. ### New commits **`backport: pin compatible dependency set and adjust #1156 for 1.8.x`** Dependency bumps are applied directly rather than cherry-picked, because taking them as-is pulls `go.temporal.io/api` past what server v1.31.2 can compile against (see *Dependency ceiling* below). Covers the isatty, x/tools, grpc, echo and testify bumps (#1145, #1148, #1132, #1175, #1174). Also pins `cliext` to a **tagged** SDK. `main` currently pins `go.temporal.io/sdk v1.46.1-0.20260720184640-f34dc3da35ab` — a commit SHA — in `cliext/go.mod`, which reaches the root build through `replace github.com/temporalio/cli/cliext => ./cliext`. That violates the tagged-dependencies rule for a public release. **`main` should be fixed separately.** **`fix(activity): use correct update-mask path for --task-queue`** Fixes a real, currently-shipping bug. `v1.8.2` sends update-mask path `task_queue_name`, which the server's `ParseFieldMask` normalizes to `taskQueueName` and which never matches its `taskQueue.name` key — so `temporal activity update-options --task-queue` **silently does nothing**. Verified A/B against the embedded server v1.31.2: - with `task_queue.name` → task queue updates as expected - with `task_queue_name` (what v1.8.2 ships) → unchanged The fix exists upstream only inside #1092, which cannot be backported, so it is extracted here as a one-liner. ## Dependency ceiling `server v1.31.2` **does not compile** against `go.temporal.io/api` ≥ **v1.62.10**: that release adds `CountNexusOperationExecutions` to the `WorkflowServiceClient` interface, which v1.31.2's `clientImpl`, `metricClient` and `retryableClient` do not implement. Because api is a transitive dependency, Go's minimal version selection drags it upward whenever anything that depends on it is bumped. That caps everything: | Dependency | Ceiling | Reason | |---|---|---| | `go.temporal.io/api` | v1.62.9 | v1.62.10 breaks server v1.31.2 | | `github.com/temporalio/ui-server/v2` | v2.50.1 | v2.51.0 → api v1.62.13; v2.53.x → api v1.63.x | | `go.temporal.io/sdk` | v1.42.0 | v1.43.1 → api v1.62.12; v1.46.0 → api v1.63.x | | `go.temporal.io/sdk/contrib/envconfig` | v1.0.0 | v1.0.1 changed `DefaultConfigFilePath` to one return value; `cliext/config.oauth.go` expects two | Resulting set — every Temporal direct dependency unchanged from `v1.8.2` except an api patch bump: ``` go.temporal.io/api v1.62.9 (was v1.62.8) go.temporal.io/server v1.31.2 unchanged go.temporal.io/sdk v1.41.1 unchanged go.temporal.io/sdk/contrib/envconfig v1.0.0 unchanged github.com/temporalio/ui-server/v2 v2.50.1 unchanged ``` **Note for the UI team:** this release ships **UI Server v2.50.1, unchanged**. The natural assumption would be v2.53.3, but that requires api v1.63.5. ## Excluded, and why ### Requires OSS Server v1.32.x / api v1.63.x | Commit | Reason | |---|---| | #1172 bump server for Nexus Query support | The server bump itself — out of scope for this line | | #1092 single SAA operator actions | Uses `Pause/Unpause/Reset ActivityExecutionRequest` and `UpdateActivityExecutionOptionsRequest`, absent from api v1.62.x | | #1152 enable SAA operator and batch commands in dev server | Needs `activity.EnableStandaloneActivityOperatorCommands` and `dynamicconfig.FrontendEnableBatchOperationsForStandaloneActivities`, absent from server v1.31.2 | | #1159 drop `activity unpause --reset-attempts`/`--reset-heartbeats` | Authored on top of #1092; its diff context already uses the new RPC names | | #1150 reject `update-options --start-delay` for workflow Activities | Needs `ActivityOptions.StartDelay`, new in api v1.63.5, via unbackported prerequisite #1113 | | #1131 render links on activity describe | Needs `ActivityExecutionInfo.GetLinks` and `DescribeActivityExecutionResponse.GetCallbacks`, new in api v1.63.5 | | #1151 bump UI server v2.53.1 | Requires api v1.63.4 | | #1164 bump UI server v2.53.3 | Requires api v1.63.5 | ### Excluded for other reasons **#1114 — staged connection diagnosis for opaque dial failures.** Depends on #1017 (*Unwrap System Nexus Operations in event history*), which introduced `dialClientWithCodec` and was never backported. On `release/1.8.x` only the two-value `dialClient` exists, and git silently misapplies #1114's hunks into it, producing three-value returns from a two-value function. Pulling in #1017 is too large for a patch release. **#1158 — docs: clarify `--query` targets Workflow Activities.** Pure documentation describing Standalone Activity semantics ("Omit `--workflow-id` to target a Standalone Activity…"). That behavior does not exist on this line, so backporting it would ship misleading help text. **#1155 — fix(activity): include options in batch `update-options`.** The change itself is correct, but batch `update-options` applies **nothing** on server v1.31.2. Probed directly: after a batch run, task queue is unchanged and `schedule_to_close_timeout` is still `0s`. Its new test `TestActivityOptionsUpdate_BatchMatchAll` fails consistently (3/3). Deferred to the release that carries the server bump. ## Reviewer notes **#1156 was adjusted rather than taken verbatim.** Upstream, `activity reset` had already lost `--reset-heartbeats` to an earlier SAA commit, so taking `main`'s version would have removed both flags at once. Only `--reset-attempts` is a no-op, the surviving help text still documents `--reset-heartbeats`, and its removal belongs to #1159 (excluded). This backport therefore removes only `--reset-attempts` and keeps the batch path on `c.ResetHeartbeats` rather than hardcoding `true`. Worth a careful look. **Known flaky test.** `TestHelp_AllFlag_ShorterCommandPathWinsi` failed on one full-suite run and passed on the next; it passes 5/5 in isolation. It arrives with #1137 and exists identically on `main`, so it is inherited rather than introduced — but expect occasional red CI. **Pre-existing `go vet` findings** (two lock-copy, one context leak) are byte-identical to the `v1.8.2` baseline. Not introduced here. --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Co-authored-by: Nanook <nanookclaw@users.noreply.github.com> Co-authored-by: mani-j9 <mani.janumpally@temporal.io> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: Jeri Lane <jeri.lane@temporal.io> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Sean Bollin <sean@sean-bollin.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Sean Kane <spkane31@gmail.com> Co-authored-by: Ross Nelson <axcess1@me.com> Co-authored-by: dryrun <dryrun@local> Co-authored-by: justinschoeff <justin.schoeff@temporal.io>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
temporal optionscommand (kubectl-style) that displays global and connection flags in a table with env var and config key columns--helpand connection flags from subcommand--help, replacing them with a hint totemporal optionshide-from-help,config-key, andDescription()support to the option set YAML spec and code generatorBefore
After
Test plan
go build ./cmd/temporalgo test ./internal/temporalcli/ -run TestHelptemporal --helpno longer shows global flagstemporal workflow --helpno longer shows connection flagstemporal workflow list --helpshows only command-specific flagstemporal optionsdisplays both tables with correct env/config columns