DO NOT MERGE: Draft work on improving help messaging #561
+1,995
−893
Conversation
This file contains 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
Also:
* Adds language for `temporal`, `temporal activity`, `temporal activity
complete` and `temporal activity fail`.
NOTES
* I'm a little confused by the inconsistency of punctuation.
* How wordy do you want the command-line usage to be? There's already an
overwhelming amount of "wall of text".
I was thinking more:
```
* `--env` (string) - Active environment name. Default: default. Env: TEMPORAL_ENV.
* `--env-file` (string) - Path to environment settings file (defaults to `$HOME/.config/temporalio/temporal.yaml`).
* `--log-level` (string-enum) - Log level. Default is "info" for most commands and "warn" for `server start-dev`.
Options: debug, info, warn, error, never. Default: info.
* `--log-format` (string) - Log format. Options are "text" and "json". Default is "text".
* `--output`, `-o` (string-enum) - Non-logging data output format. Options: text, json, jsonl,
none. Default: text.
* `--time-format` (string-enum) - Time format. Options: relative, iso, raw. Default: relative.
* `--color` (string-enum) - Output coloring. Options: always, never, auto. Default: auto.
* `--no-json-shorthand-payloads` (bool) - Show all payloads as raw, even if they are JSON. Default: false.
```
over
```
* `--env` (string) - Read additional options from the `ENV` environment. (See "temporal env --help" for more about environments.) Default: default. Env: TEMPORAL_ENV.
* `--env-file` (string) - Read/store per-environment configuration in `PATH` (defaults to "$HOME/.config/temporalio/temporal.yaml").
* `--log-level` (string-enum) - Log level. Default is "info" for most commands and "warn" for the development server.
Options: debug, info, warn, error, never. Default: info.
* `--log-format` (string) - Emit log messages in "text" or "json" format. Default is "text".
* `--output`, `-o` (string-enum) - Emit output in the `FMT` format. Does not affect logs; use --log-format instead. Options: text, json, jsonl,
none. Default: text.
* `--time-format` (string-enum) - Emit timestamps in the `FMT` format. Options: relative, iso, raw. Default: relative.
* `--color` (string-enum) - Colorize output. Does not affect logs. Options: always, never, auto. Default: auto.
* `--no-json-shorthand-payloads` (bool) - Show all payloads as raw payloads even if they are JSON.
```
ISSUES
1. There's no way to bundle the `temporal` options, which are
imported elsewhere. They have to be there and they are
distracting, and contribute to overwhelmed users.
2. Even though I set a description for complete and fail, they are not shown
cli% ./temporal activity complete
Error: required flag(s) "activity-id", "result", "workflow-id" not set
Usage:
temporal activity complete [flags]
Ditto for temporal activity fail.
Proof of concept material is pretty much there before I move forward.
fairlydurable
commented
May 14, 2024
fairlydurable
commented
May 14, 2024
fairlydurable
commented
May 14, 2024
fairlydurable
commented
May 14, 2024
fairlydurable
commented
May 14, 2024
fairlydurable
commented
May 14, 2024
fairlydurable
commented
May 14, 2024
fairlydurable
commented
May 14, 2024
fairlydurable
commented
May 14, 2024
josh-berry
reviewed
May 15, 2024
Flags (booleans) and updated links, plus applied updates for links
josh-berry
reviewed
May 31, 2024
|
|
||
| * All URLs are borked due to Info Arch re-org (fixed for now) | ||
| * What changes have been introduced asynchronously. I've seen stuff on Slack. | ||
| * What's the best way to do async conversations other than PRs? |
There was a problem hiding this comment.
Slack or email works too.
| NOTES FOR ERICA | ||
|
|
||
| * All URLs are borked due to Info Arch re-org (fixed for now) | ||
| * What changes have been introduced asynchronously. I've seen stuff on Slack. |
There was a problem hiding this comment.
Since you last rebased, here's what I can see:
diff --git a/temporalcli/commandsmd/commands.md b/temporalcli/commandsmd/commands.md
index 175feef..a4a0224 100644
--- a/temporalcli/commandsmd/commands.md
+++ b/temporalcli/commandsmd/commands.md
@@ -201,6 +201,10 @@ If the environment is not specified, the `default` environment is used.
List all environments.
+<!--
+* ignores-missing-env
+-->
+
### temporal env set: Set environment properties.
`temporal env set --env environment -k property -v value`
@@ -214,6 +218,7 @@ If the environment is not specified, the `default` environment is used.
<!--
* maximum-args=2
+* ignores-missing-env
-->
#### Options
@@ -815,9 +820,8 @@ temporal workflow execute
#### Options
-* `--event-details` (bool) - If set when using text output, this will print the event details instead of just the event
- during workflow progress. If set when using JSON output, this will include the entire "history" JSON key of the
- started run (does not follow runs).
+* `--event-details` (bool) - If set when using text output, include event details JSON in printed output. If set when
+ using JSON output, this will include the entire "history" JSON key of the started run (does not follow runs).
Includes options set for [shared workflow start](#options-set-for-shared-workflow-start).
Includes options set for [workflow start](#options-set-for-workflow-start).
@@ -926,6 +930,7 @@ Use the options listed below to change the command's behavior.
* `--follow`, `-f` (bool) - Follow the progress of a Workflow Execution in real time (does not apply
to JSON output).
+* `--event-details` (bool) - If set when using text output, include event details JSON in printed output.
Includes options set for [workflow reference](#options-set-for-workflow-reference).You can see this yourself using:
git fetch origin
git diff ...origin/main -- temporalcli/commandsmd/commands.md| or something like that because mind blown. | ||
|
|
||
| * Word wrapping to 80 chars | ||
| * What about options? they tend to run long |
There was a problem hiding this comment.
Yes, options can also be wrapped.
|
|
||
| * Word wrapping to 80 chars | ||
| * What about options? they tend to run long | ||
| * Could the text go to a second line after the spaced-dash? |
| * Word wrapping to 80 chars | ||
| * What about options? they tend to run long | ||
| * Could the text go to a second line after the spaced-dash? | ||
| * Could long descriptions be autowrapped outside code examples? -- NEW Q |
There was a problem hiding this comment.
Yes; we should probably track that as a separate issue though (outside this PR).
| [Signal](/workflows#signal) | ||
| [Update](/workflows#update) | ||
|
|
||
| * -h, -o, -v are wonky: |
There was a problem hiding this comment.
The alignment is intentional, I think, if that's what you're referring to—short options are usually shown before long options in the CLI tool we use (and in most others I'm aware of, since most people prefer short options—less typing).
| * `--ui-port` (int) - | ||
|
|
||
|
|
||
| ---- |
There was a problem hiding this comment.
We can start a separate (internal) Notion page with all of the above, I think; some/many of these are breaking changes, so we need to decide if it's worth breaking people's scripts and such for this. But we should definitely capture all of this in one place (along with what you had in your Google doc). LMK if you want me to start a page somewhere.
| example. | ||
| Use square brackets to highlight its optional nature if the long | ||
| description would suffer from two very similar command invocations. | ||
| * Use YourEnvironment, YourNamespace, etc as metasyntactic stand-ins. |
There was a problem hiding this comment.
We should probably be consistent with the META-VARIABLES in the flags.
josh-berry
reviewed
May 31, 2024
|
|
||
| Includes options set for [workflow reference](#options-set-for-workflow-reference). | ||
|
|
||
| ### temporal batch: Manage batch jobs | ||
|
|
|
|
||
| #### Options | ||
|
|
||
| * `--limit` (int) - Limit the number of items to print. | ||
| * `--limit` (int) - | ||
| Max output count. |
There was a problem hiding this comment.
This seems a little obtuse—"count" of what?
Comment on lines
+532
to
+533
| Terminate a batch job with the provided job ID. Provide a reason for the | ||
| termination. This explanation is stored with the Service for later reference. |
There was a problem hiding this comment.
Suggested change
| Terminate a batch job with the provided job ID. Provide a reason for the | |
| termination. This explanation is stored with the Service for later reference. | |
| Terminate a batch job with the provided job ID. You must provide a reason for the | |
| termination. This explanation is stored with the Service for later reference. |
Comment on lines
+553
to
+555
| Environments manage key-value presets, auto-configuring Temporal CLI options | ||
| for you. Set up distinct environments like "dev" and "prod" for convenience. | ||
| For example: |
There was a problem hiding this comment.
Suggested change
| Environments manage key-value presets, auto-configuring Temporal CLI options | |
| for you. Set up distinct environments like "dev" and "prod" for convenience. | |
| For example: | |
| Environments manage key-value presets, auto-configuring Temporal CLI options | |
| for you. You can set up distinct environments like "dev" and "prod" for convenience. | |
| For example: |
| or | ||
|
|
||
| ``` | ||
| temporal env delete --env prod --key tls-key-path |
There was a problem hiding this comment.
extra space before --key
| ``` | ||
|
|
||
| If the environment is not specified, the `default` environment is used. | ||
| If you don't specify an environment name, with `--env` or by setting | ||
| `TEMPORAL_ENV` as an environmental variable in your shell, this command |
There was a problem hiding this comment.
Suggested change
| `TEMPORAL_ENV` as an environmental variable in your shell, this command | |
| `TEMPORAL_ENV` as an environment variable in your shell, this command |
Comment on lines
+627
to
+629
| List the environments you have set up on your local computer. The output | ||
| enumerates the environments stored in the Temporal environment file on | ||
| your computer ("$HOME/.config/temporalio/temporal.yaml"). |
There was a problem hiding this comment.
Suggested change
| List the environments you have set up on your local computer. The output | |
| enumerates the environments stored in the Temporal environment file on | |
| your computer ("$HOME/.config/temporalio/temporal.yaml"). | |
| List the environments you have set up on your local computer. | |
| Environments are stored in "$HOME/.config/temporalio/temporal.yaml". |
(Sorry I'm not getting the wrapping exactly right on these suggestions; hard to do in GitHub's UI)
| `temporal env set --env prod -k address -v 127.0.0.1:7233` | ||
| `temporal env set --env prod -k tls-cert-path -v /home/my-user/certs/cluster.cert` | ||
| If you don't specify an environment name, with `--env` or by setting | ||
| `TEMPORAL_ENV` as an environmental variable in your shell, this command |
There was a problem hiding this comment.
Suggested change
| `TEMPORAL_ENV` as an environmental variable in your shell, this command | |
| `TEMPORAL_ENV` as an environment variable in your shell, this command |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
EDU-2415: Docs team assist for
temporalCLI help text