From 090a71b7475a9a8425c69cae854acbee3f7a6d1a Mon Sep 17 00:00:00 2001 From: Erica Sadun <156466156+fairlydurable@users.noreply.github.com> Date: Thu, 25 Jul 2024 09:58:30 -0600 Subject: [PATCH] Improve CLI Help content (#561) Erica/Josh did a pass at all the CLI --help output to clean it up and make it more readable. Co-authored-by: Josh Berry --- Makefile | 11 + temporalcli/commands.gen.go | 900 +++++----- temporalcli/commandsmd/commands.md | 2636 +++++++++++++++++++++------- temporalcli/commandsmd/parse.go | 3 - 4 files changed, 2493 insertions(+), 1057 deletions(-) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..7c510a90 --- /dev/null +++ b/Makefile @@ -0,0 +1,11 @@ +.PHONY: all gen build + +all: gen build + +gen: temporalcli/commands.gen.go + +temporalcli/commands.gen.go: temporalcli/commandsmd/commands.md + go run ./temporalcli/internal/cmd/gen-commands + +build: + go build ./cmd/temporal diff --git a/temporalcli/commands.gen.go b/temporalcli/commands.gen.go index 3243fb51..4eca76cc 100644 --- a/temporalcli/commands.gen.go +++ b/temporalcli/commands.gen.go @@ -31,8 +31,12 @@ type TemporalCommand struct { func NewTemporalCommand(cctx *CommandContext) *TemporalCommand { var s TemporalCommand s.Command.Use = "temporal" - s.Command.Short = "Temporal command-line interface and development server." - s.Command.Long = "" + s.Command.Short = "Temporal command-line interface and development server" + if hasHighlighting { + s.Command.Long = "The Temporal CLI manages, monitors, and debugs Temporal apps. It lets you run\na local Temporal Service, start Workflow Executions, pass messages to running\nWorkflows, inspect state, and more.\n\n* Start a local development service:\n \x1b[1mtemporal server start-dev\x1b[0m\n* View help: pass \x1b[1m--help\x1b[0m to any command:\n \x1b[1mtemporal activity complete --help\x1b[0m" + } else { + s.Command.Long = "The Temporal CLI manages, monitors, and debugs Temporal apps. It lets you run\na local Temporal Service, start Workflow Executions, pass messages to running\nWorkflows, inspect state, and more.\n\n* Start a local development service:\n `temporal server start-dev`\n* View help: pass `--help` to any command:\n `temporal activity complete --help`" + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalActivityCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalBatchCommand(cctx, &s).Command) @@ -42,19 +46,19 @@ func NewTemporalCommand(cctx *CommandContext) *TemporalCommand { s.Command.AddCommand(&NewTemporalServerCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalTaskQueueCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalWorkflowCommand(cctx, &s).Command) - s.Command.PersistentFlags().StringVar(&s.Env, "env", "default", "Environment to read environment-specific flags from.") + s.Command.PersistentFlags().StringVar(&s.Env, "env", "default", "Active environment name (`ENV`).") cctx.BindFlagEnvVar(s.Command.PersistentFlags().Lookup("env"), "TEMPORAL_ENV") - s.Command.PersistentFlags().StringVar(&s.EnvFile, "env-file", "", "File to read all environments (defaults to `$HOME/.config/temporalio/temporal.yaml`).") + s.Command.PersistentFlags().StringVar(&s.EnvFile, "env-file", "", "Path to environment settings file. (defaults to `$HOME/.config/temporalio/temporal.yaml`).") s.LogLevel = NewStringEnum([]string{"debug", "info", "warn", "error", "never"}, "info") s.Command.PersistentFlags().Var(&s.LogLevel, "log-level", "Log level. Default is \"info\" for most commands and \"warn\" for `server start-dev`. Accepted values: debug, info, warn, error, never.") - s.Command.PersistentFlags().StringVar(&s.LogFormat, "log-format", "", "Log format. Options are \"text\" and \"json\". Default is \"text\".") + s.Command.PersistentFlags().StringVar(&s.LogFormat, "log-format", "", "Log format. Options are: text, json. Defaults to: text.") s.Output = NewStringEnum([]string{"text", "json", "jsonl", "none"}, "text") - s.Command.PersistentFlags().VarP(&s.Output, "output", "o", "Data output format. Note, this does not affect logging. Accepted values: text, json, jsonl, none.") + s.Command.PersistentFlags().VarP(&s.Output, "output", "o", "Non-logging data output format. Accepted values: text, json, jsonl, none.") s.TimeFormat = NewStringEnum([]string{"relative", "iso", "raw"}, "relative") s.Command.PersistentFlags().Var(&s.TimeFormat, "time-format", "Time format. Accepted values: relative, iso, raw.") s.Color = NewStringEnum([]string{"always", "never", "auto"}, "auto") - s.Command.PersistentFlags().Var(&s.Color, "color", "Set coloring. Accepted values: always, never, auto.") - s.Command.PersistentFlags().BoolVar(&s.NoJsonShorthandPayloads, "no-json-shorthand-payloads", false, "Always show all payloads as raw payloads even if they are JSON.") + s.Command.PersistentFlags().Var(&s.Color, "color", "Output coloring. Accepted values: always, never, auto.") + s.Command.PersistentFlags().BoolVar(&s.NoJsonShorthandPayloads, "no-json-shorthand-payloads", false, "Raw payload output, even if they are JSON.") s.initCommand(cctx) return &s } @@ -69,8 +73,12 @@ func NewTemporalActivityCommand(cctx *CommandContext, parent *TemporalCommand) * var s TemporalActivityCommand s.Parent = parent s.Command.Use = "activity" - s.Command.Short = "Complete or fail an Activity." - s.Command.Long = "" + s.Command.Short = "Complete or fail an Activity" + if hasHighlighting { + s.Command.Long = "Update an Activity's state to completed or failed. This marks an Activity\nas successfully finished or as having encountered an error:\n\n\x1b[1mtemporal activity complete \\\n --activity-id=YourActivityId \\\n --workflow-id=YourWorkflowId \\\n --result='{\"YourResultKey\": \"YourResultValue\"}'\x1b[0m" + } else { + s.Command.Long = "Update an Activity's state to completed or failed. This marks an Activity\nas successfully finished or as having encountered an error:\n\n```\ntemporal activity complete \\\n --activity-id=YourActivityId \\\n --workflow-id=YourWorkflowId \\\n --result='{\"YourResultKey\": \"YourResultValue\"}'\n```" + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalActivityCompleteCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalActivityFailCommand(cctx, &s).Command) @@ -83,8 +91,8 @@ type TemporalActivityCompleteCommand struct { Command cobra.Command WorkflowReferenceOptions ActivityId string - Identity string Result string + Identity string } func NewTemporalActivityCompleteCommand(cctx *CommandContext, parent *TemporalActivityCommand) *TemporalActivityCompleteCommand { @@ -92,19 +100,19 @@ func NewTemporalActivityCompleteCommand(cctx *CommandContext, parent *TemporalAc s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "complete [flags]" - s.Command.Short = "Complete an Activity." + s.Command.Short = "Complete an Activity" if hasHighlighting { - s.Command.Long = "Complete an Activity.\n\n\x1b[1mtemporal activity complete --activity-id=MyActivityId --workflow-id=MyWorkflowId --result='{\"MyResultKey\": \"MyResultVal\"}'\x1b[0m" + s.Command.Long = "Complete an Activity, marking it as successfully finished. Specify the\nActivity ID and include a JSON result for the returned value:\n\n\x1b[1mtemporal activity complete \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId \\\n --result '{\"YourResultKey\": \"YourResultVal\"}'\x1b[0m" } else { - s.Command.Long = "Complete an Activity.\n\n`temporal activity complete --activity-id=MyActivityId --workflow-id=MyWorkflowId --result='{\"MyResultKey\": \"MyResultVal\"}'`" + s.Command.Long = "Complete an Activity, marking it as successfully finished. Specify the\nActivity ID and include a JSON result for the returned value:\n\n```\ntemporal activity complete \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId \\\n --result '{\"YourResultKey\": \"YourResultVal\"}'\n```" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "The Activity to be completed. Required.") + s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "Activity ID to complete. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "activity-id") - s.Command.Flags().StringVar(&s.Identity, "identity", "", "Identity of user submitting this request.") - s.Command.Flags().StringVar(&s.Result, "result", "", "The result with which to complete the Activity (JSON). Required.") + s.Command.Flags().StringVar(&s.Result, "result", "", "Result `JSON` to return. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "result") + s.Command.Flags().StringVar(&s.Identity, "identity", "", "Identity of the user submitting this request.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -128,18 +136,18 @@ func NewTemporalActivityFailCommand(cctx *CommandContext, parent *TemporalActivi s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "fail [flags]" - s.Command.Short = "Fail an Activity." + s.Command.Short = "Fail an Activity" if hasHighlighting { - s.Command.Long = "Fail an Activity.\n\n\x1b[1mtemporal activity fail --activity-id=MyActivityId --workflow-id=MyWorkflowId\x1b[0m" + s.Command.Long = "Fail an Activity, marking it as having encountered an error. Specify the\nActivity and Workflow IDs:\n\n\x1b[1mtemporal activity fail \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\x1b[0m" } else { - s.Command.Long = "Fail an Activity.\n\n`temporal activity fail --activity-id=MyActivityId --workflow-id=MyWorkflowId`" + s.Command.Long = "Fail an Activity, marking it as having encountered an error. Specify the\nActivity and Workflow IDs:\n\n```\ntemporal activity fail \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n```" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "The Activity to be failed. Required.") + s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "Activity ID to fail. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "activity-id") - s.Command.Flags().StringVar(&s.Detail, "detail", "", "JSON data describing reason for failing the Activity.") - s.Command.Flags().StringVar(&s.Identity, "identity", "", "Identity of user submitting this request.") + s.Command.Flags().StringVar(&s.Detail, "detail", "", "Reason for failing the Activity (JSON).") + s.Command.Flags().StringVar(&s.Identity, "identity", "", "Identity of the user submitting this request.") s.Command.Flags().StringVar(&s.Reason, "reason", "", "Reason for failing the Activity.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -159,8 +167,12 @@ func NewTemporalBatchCommand(cctx *CommandContext, parent *TemporalCommand) *Tem var s TemporalBatchCommand s.Parent = parent s.Command.Use = "batch" - s.Command.Short = "Manage Batch Jobs" - s.Command.Long = "Batch commands change multiple Workflow Executions." + s.Command.Short = "Manage running batch jobs" + if hasHighlighting { + s.Command.Long = "List or terminate running batch jobs.\n\nA batch job executes a command on multiple Workflow Executions at once. Create\nbatch jobs by passing \x1b[1m--query\x1b[0m to commands that support it. For example, to\ncreate a batch job to cancel a set of Workflow Executions:\n\n\x1b[1mtemporal workflow cancel \\\n --query 'ExecutionStatus = \"Running\" AND WorkflowType=\"YourWorkflow\"' \\\n --reason \"Testing\"\x1b[0m\n\nQuery Quick Reference:\n\n\x1b[1m+----------------------------------------------------------------------------+\n| Composition: |\n| - Data types: String literals with single or double quotes, |\n| Numbers (integer and floating point), Booleans |\n| - Comparison: '=', '!=', '>', '>=', '<', '<=' |\n| - Expressions/Operators: 'IN array', 'BETWEEN value AND value', |\n| 'STARTS_WITH string', 'IS NULL', 'IS NOT NULL', 'expr AND expr', |\n| 'expr OR expr', '( expr )' |\n| - Array: '( comma-separated-values )' |\n| |\n| Please note: |\n| - Wrap attributes with backticks if it contains characters not in |\n| \x1b[1m[a-zA-Z0-9]\x1b[0m. |\n| - \x1b[1mSTARTS_WITH\x1b[0m is only available for Keyword search attributes. |\n+----------------------------------------------------------------------------+\x1b[0m\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation." + } else { + s.Command.Long = "List or terminate running batch jobs.\n\nA batch job executes a command on multiple Workflow Executions at once. Create\nbatch jobs by passing `--query` to commands that support it. For example, to\ncreate a batch job to cancel a set of Workflow Executions:\n\n```\ntemporal workflow cancel \\\n --query 'ExecutionStatus = \"Running\" AND WorkflowType=\"YourWorkflow\"' \\\n --reason \"Testing\"\n```\n\nQuery Quick Reference:\n\n```\n+----------------------------------------------------------------------------+\n| Composition: |\n| - Data types: String literals with single or double quotes, |\n| Numbers (integer and floating point), Booleans |\n| - Comparison: '=', '!=', '>', '>=', '<', '<=' |\n| - Expressions/Operators: 'IN array', 'BETWEEN value AND value', |\n| 'STARTS_WITH string', 'IS NULL', 'IS NOT NULL', 'expr AND expr', |\n| 'expr OR expr', '( expr )' |\n| - Array: '( comma-separated-values )' |\n| |\n| Please note: |\n| - Wrap attributes with backticks if it contains characters not in |\n| `[a-zA-Z0-9]`. |\n| - `STARTS_WITH` is only available for Keyword search attributes. |\n+----------------------------------------------------------------------------+\n```\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation." + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalBatchDescribeCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalBatchListCommand(cctx, &s).Command) @@ -180,14 +192,14 @@ func NewTemporalBatchDescribeCommand(cctx *CommandContext, parent *TemporalBatch s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "describe [flags]" - s.Command.Short = "Show Batch Job progress." + s.Command.Short = "Show batch job progress" if hasHighlighting { - s.Command.Long = "The temporal batch describe command shows the progress of an ongoing Batch Job.\n\n\x1b[1mtemporal batch describe --job-id=MyJobId\x1b[0m" + s.Command.Long = "Show the progress of an ongoing batch job. Pass a valid job ID to display its\ninformation:\n\n\x1b[1mtemporal batch describe \\\n --job-id YourJobId\x1b[0m" } else { - s.Command.Long = "The temporal batch describe command shows the progress of an ongoing Batch Job.\n\n`temporal batch describe --job-id=MyJobId`" + s.Command.Long = "Show the progress of an ongoing batch job. Pass a valid job ID to display its\ninformation:\n\n```\ntemporal batch describe \\\n --job-id YourJobId\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.JobId, "job-id", "", "The Batch Job Id to describe. Required.") + s.Command.Flags().StringVar(&s.JobId, "job-id", "", "Batch job ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "job-id") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -208,14 +220,14 @@ func NewTemporalBatchListCommand(cctx *CommandContext, parent *TemporalBatchComm s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "list [flags]" - s.Command.Short = "List all Batch Jobs" + s.Command.Short = "List all batch jobs" if hasHighlighting { - s.Command.Long = "The temporal batch list command returns all Batch Jobs.\nBatch Jobs can be returned for an entire Cluster or a single Namespace.\n\n\x1b[1mtemporal batch list --namespace=MyNamespace\x1b[0m" + s.Command.Long = "Return a list of batch jobs on the Service or within a single Namespace. For\nexample, list the batch jobs for \"YourNamespace\":\n\n\x1b[1mtemporal batch list \\\n --namespace YourNamespace\x1b[0m" } else { - s.Command.Long = "The temporal batch list command returns all Batch Jobs.\nBatch Jobs can be returned for an entire Cluster or a single Namespace.\n\n`temporal batch list --namespace=MyNamespace`" + s.Command.Long = "Return a list of batch jobs on the Service or within a single Namespace. For\nexample, list the batch jobs for \"YourNamespace\":\n\n```\ntemporal batch list \\\n --namespace YourNamespace\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Limit the number of items to print.") + s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Maximum number of batch jobs to display.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -236,16 +248,16 @@ func NewTemporalBatchTerminateCommand(cctx *CommandContext, parent *TemporalBatc s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "terminate [flags]" - s.Command.Short = "Terminate a Batch Job" + s.Command.Short = "Forcefully end a batch job" if hasHighlighting { - s.Command.Long = "The temporal batch terminate command terminates a Batch Job with the provided Job Id.\nFor future reference, provide a reason for terminating the Batch Job.\n\n\x1b[1mtemporal batch terminate --job-id=MyJobId --reason=JobReason\x1b[0m" + s.Command.Long = "Terminate a batch job with the provided job ID. You must provide a reason for\nthe termination. The Service stores this explanation as metadata for the\ntermination event for later reference:\n\n\x1b[1mtemporal batch terminate \\\n --job-id YourJobId \\\n --reason YourTerminationReason\x1b[0m" } else { - s.Command.Long = "The temporal batch terminate command terminates a Batch Job with the provided Job Id.\nFor future reference, provide a reason for terminating the Batch Job.\n\n`temporal batch terminate --job-id=MyJobId --reason=JobReason`" + s.Command.Long = "Terminate a batch job with the provided job ID. You must provide a reason for\nthe termination. The Service stores this explanation as metadata for the\ntermination event for later reference:\n\n```\ntemporal batch terminate \\\n --job-id YourJobId \\\n --reason YourTerminationReason\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.JobId, "job-id", "", "The Batch Job Id to terminate. Required.") + s.Command.Flags().StringVar(&s.JobId, "job-id", "", "Job Id to terminate. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "job-id") - s.Command.Flags().StringVar(&s.Reason, "reason", "", "Reason for terminating the Batch Job. Required.") + s.Command.Flags().StringVar(&s.Reason, "reason", "", "Reason for terminating the batch job. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "reason") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -264,8 +276,12 @@ func NewTemporalEnvCommand(cctx *CommandContext, parent *TemporalCommand) *Tempo var s TemporalEnvCommand s.Parent = parent s.Command.Use = "env" - s.Command.Short = "Manage environments." - s.Command.Long = "Use the '--env ' option with other commands to point the CLI at a different Temporal Server instance. If --env\nis not passed, the 'default' environment is used." + s.Command.Short = "Manage environments" + if hasHighlighting { + s.Command.Long = "Environments manage key-value presets, auto-configuring Temporal CLI options\nfor you. You can set up distinct environments like \"dev\" and \"prod\" for\nconvenience:\n\n\x1b[1mtemporal env set \\\n --env prod \\\n --key address \\\n --value production.f45a2.tmprl.cloud:7233\x1b[0m\n\nEach environment is isolated. Changes to \"prod\" presets won't affect \"dev\".\n\nFor easiest use, set a \x1b[1mTEMPORAL_ENV\x1b[0m environment variable in your shell. The\nTemporal CLI checks for an \x1b[1m--env\x1b[0m option first, then checks for the\n\x1b[1mTEMPORAL_ENV\x1b[0m environment variable. If neither is set, the CLI uses the\n\"default\" environment." + } else { + s.Command.Long = "Environments manage key-value presets, auto-configuring Temporal CLI options\nfor you. You can set up distinct environments like \"dev\" and \"prod\" for\nconvenience:\n\n```\ntemporal env set \\\n --env prod \\\n --key address \\\n --value production.f45a2.tmprl.cloud:7233\n```\n\nEach environment is isolated. Changes to \"prod\" presets won't affect \"dev\".\n\nFor easiest use, set a `TEMPORAL_ENV` environment variable in your shell. The\nTemporal CLI checks for an `--env` option first, then checks for the\n`TEMPORAL_ENV` environment variable. If neither is set, the CLI uses the\n\"default\" environment." + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalEnvDeleteCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalEnvGetCommand(cctx, &s).Command) @@ -285,14 +301,14 @@ func NewTemporalEnvDeleteCommand(cctx *CommandContext, parent *TemporalEnvComman s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "delete [flags]" - s.Command.Short = "Delete an environment or environment property." + s.Command.Short = "Delete an environment or environment property" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal env delete --env environment [-k property]\x1b[0m\n\nDelete an environment or just a single property:\n\n\x1b[1mtemporal env delete --env prod\x1b[0m\n\x1b[1mtemporal env delete --env prod -k tls-cert-path\x1b[0m\n\nIf the environment is not specified, the \x1b[1mdefault\x1b[0m environment is deleted:\n\n\x1b[1mtemporal env delete -k tls-cert-path\x1b[0m" + s.Command.Long = "Remove a presets environment entirely _or_ remove a key-value pair within an\nenvironment. If you don't specify an environment (with \x1b[1m--env\x1b[0m or by setting\nthe \x1b[1mTEMPORAL_ENV\x1b[0m variable), this command updates the \"default\" environment:\n\n\x1b[1mtemporal env delete \\\n --env YourEnvironment\x1b[0m\n\nor\n\n\x1b[1mtemporal env delete \\\n --env prod \\\n --key tls-key-path\x1b[0m" } else { - s.Command.Long = "`temporal env delete --env environment [-k property]`\n\nDelete an environment or just a single property:\n\n`temporal env delete --env prod`\n`temporal env delete --env prod -k tls-cert-path`\n\nIf the environment is not specified, the `default` environment is deleted:\n\n`temporal env delete -k tls-cert-path`" + s.Command.Long = "Remove a presets environment entirely _or_ remove a key-value pair within an\nenvironment. If you don't specify an environment (with `--env` or by setting\nthe `TEMPORAL_ENV` variable), this command updates the \"default\" environment:\n\n```\ntemporal env delete \\\n --env YourEnvironment\n```\n\nor\n\n```\ntemporal env delete \\\n --env prod \\\n --key tls-key-path\n```" } s.Command.Args = cobra.MaximumNArgs(1) - s.Command.Flags().StringVarP(&s.Key, "key", "k", "", "The name of the property.") + s.Command.Flags().StringVarP(&s.Key, "key", "k", "", "Property name.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -312,14 +328,14 @@ func NewTemporalEnvGetCommand(cctx *CommandContext, parent *TemporalEnvCommand) s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "get [flags]" - s.Command.Short = "Print environment properties." + s.Command.Short = "Show environment properties" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal env get --env environment\x1b[0m\n\nPrint all properties of the 'prod' environment:\n\n\x1b[1mtemporal env get prod\x1b[0m\n\n\x1b[1mtls-cert-path /home/my-user/certs/client.cert\ntls-key-path /home/my-user/certs/client.key\naddress temporal.example.com:7233\nnamespace someNamespace\x1b[0m\n\nPrint a single property:\n\n\x1b[1mtemporal env get --env prod -k tls-key-path\x1b[0m\n\n\x1b[1mtls-key-path /home/my-user/certs/cluster.key\x1b[0m\n\nIf the environment is not specified, the \x1b[1mdefault\x1b[0m environment is used." + s.Command.Long = "List the properties for a given environment:\n\n\x1b[1mtemporal env get \\\n --env YourEnvironment\x1b[0m\n\nPrint a single property:\n\n\x1b[1mtemporal env get \\\n --env YourEnvironment \\\n --key YourPropertyKey\x1b[0m\n\nIf you don't specify an environment (with \x1b[1m--env\x1b[0m or by setting the\n\x1b[1mTEMPORAL_ENV\x1b[0m variable), this command lists properties of the \"default\"\nenvironment." } else { - s.Command.Long = "`temporal env get --env environment`\n\nPrint all properties of the 'prod' environment:\n\n`temporal env get prod`\n\n```\ntls-cert-path /home/my-user/certs/client.cert\ntls-key-path /home/my-user/certs/client.key\naddress temporal.example.com:7233\nnamespace someNamespace\n```\n\nPrint a single property:\n\n`temporal env get --env prod -k tls-key-path`\n\n```\ntls-key-path /home/my-user/certs/cluster.key\n```\n\nIf the environment is not specified, the `default` environment is used." + s.Command.Long = "List the properties for a given environment:\n\n```\ntemporal env get \\\n --env YourEnvironment\n```\n\nPrint a single property:\n\n```\ntemporal env get \\\n --env YourEnvironment \\\n --key YourPropertyKey\n```\n\nIf you don't specify an environment (with `--env` or by setting the\n`TEMPORAL_ENV` variable), this command lists properties of the \"default\"\nenvironment." } s.Command.Args = cobra.MaximumNArgs(1) - s.Command.Flags().StringVarP(&s.Key, "key", "k", "", "The name of the property.") + s.Command.Flags().StringVarP(&s.Key, "key", "k", "", "Property name.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -338,8 +354,8 @@ func NewTemporalEnvListCommand(cctx *CommandContext, parent *TemporalEnvCommand) s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "list [flags]" - s.Command.Short = "Print all environments." - s.Command.Long = "List all environments." + s.Command.Short = "Show environment names" + s.Command.Long = "List the environments you have set up on your local computer. Environments are\nstored in \"$HOME/.config/temporalio/temporal.yaml\"." s.Command.Args = cobra.NoArgs s.Command.Annotations = make(map[string]string) s.Command.Annotations["ignoresMissingEnv"] = "true" @@ -363,17 +379,17 @@ func NewTemporalEnvSetCommand(cctx *CommandContext, parent *TemporalEnvCommand) s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "set [flags]" - s.Command.Short = "Set environment properties." + s.Command.Short = "Set environment properties" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal env set --env environment -k property -v value\x1b[0m\n\nProperty names match CLI option names, for example '--address' and '--tls-cert-path':\n\n\x1b[1mtemporal env set --env prod -k address -v 127.0.0.1:7233\x1b[0m\n\x1b[1mtemporal env set --env prod -k tls-cert-path -v /home/my-user/certs/cluster.cert\x1b[0m\n\nIf the environment is not specified, the \x1b[1mdefault\x1b[0m environment is used." + s.Command.Long = "Assign a value to a property key and store it to an environment:\n\n\x1b[1mtemporal env set \\\n --env environment \\\n --key property \\\n --value value\x1b[0m\n\nIf you don't specify an environment (with \x1b[1m--env\x1b[0m or by setting the\n\x1b[1mTEMPORAL_ENV\x1b[0m variable), this command sets properties in the \"default\"\nenvironment.\n\nStoring keys with CLI option names lets the CLI automatically set those\noptions for you. This reduces effort and helps avoid typos when issuing\ncommands." } else { - s.Command.Long = "`temporal env set --env environment -k property -v value`\n\nProperty names match CLI option names, for example '--address' and '--tls-cert-path':\n\n`temporal env set --env prod -k address -v 127.0.0.1:7233`\n`temporal env set --env prod -k tls-cert-path -v /home/my-user/certs/cluster.cert`\n\nIf the environment is not specified, the `default` environment is used." + s.Command.Long = "Assign a value to a property key and store it to an environment:\n\n```\ntemporal env set \\\n --env environment \\\n --key property \\\n --value value\n```\n\nIf you don't specify an environment (with `--env` or by setting the\n`TEMPORAL_ENV` variable), this command sets properties in the \"default\"\nenvironment.\n\nStoring keys with CLI option names lets the CLI automatically set those\noptions for you. This reduces effort and helps avoid typos when issuing\ncommands." } s.Command.Args = cobra.MaximumNArgs(2) s.Command.Annotations = make(map[string]string) s.Command.Annotations["ignoresMissingEnv"] = "true" - s.Command.Flags().StringVarP(&s.Key, "key", "k", "", "The name of the property.") - s.Command.Flags().StringVarP(&s.Value, "value", "v", "", "The value to set the property to.") + s.Command.Flags().StringVarP(&s.Key, "key", "k", "", "Property name (required).") + s.Command.Flags().StringVarP(&s.Value, "value", "v", "", "Property value (required).") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -392,11 +408,11 @@ func NewTemporalOperatorCommand(cctx *CommandContext, parent *TemporalCommand) * var s TemporalOperatorCommand s.Parent = parent s.Command.Use = "operator" - s.Command.Short = "Manage a Temporal deployment." + s.Command.Short = "Manage Temporal deployments" if hasHighlighting { - s.Command.Long = "Operator commands enable actions on Namespaces, Search Attributes, and Temporal Clusters. These actions are performed through subcommands.\n\nTo run an Operator command, \x1b[1mrun temporal operator [command] [subcommand] [command options]\x1b[0m" + s.Command.Long = "Operator commands manage and fetch information about Namespaces, Search\nAttributes, and Temporal Services:\n\n\x1b[1mtemporal operator [command] [subcommand] [options]\x1b[0m\n\nFor example, to show information about the Temporal Service at the default\naddress (localhost):\n\n\x1b[1mtemporal operator cluster describe\x1b[0m" } else { - s.Command.Long = "Operator commands enable actions on Namespaces, Search Attributes, and Temporal Clusters. These actions are performed through subcommands.\n\nTo run an Operator command, `run temporal operator [command] [subcommand] [command options]`" + s.Command.Long = "Operator commands manage and fetch information about Namespaces, Search\nAttributes, and Temporal Services:\n\n```\ntemporal operator [command] [subcommand] [options]\n```\n\nFor example, to show information about the Temporal Service at the default\naddress (localhost):\n\n```\ntemporal operator cluster describe\n```" } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalOperatorClusterCommand(cctx, &s).Command) @@ -415,11 +431,11 @@ func NewTemporalOperatorClusterCommand(cctx *CommandContext, parent *TemporalOpe var s TemporalOperatorClusterCommand s.Parent = parent s.Command.Use = "cluster" - s.Command.Short = "Operations for running a Temporal Cluster." + s.Command.Short = "Manage a Temporal Cluster" if hasHighlighting { - s.Command.Long = "Cluster commands enable actions on Temporal Clusters.\n\nCluster commands follow this syntax: \x1b[1mtemporal operator cluster [command] [command options]\x1b[0m" + s.Command.Long = "Perform operator actions on Temporal Services (also known as Clusters).\n\n\x1b[1mtemporal operator cluster [subcommand] [options]\x1b[0m\n\nFor example to check Service/Cluster health:\n\n\x1b[1mtemporal operator cluster health\x1b[0m" } else { - s.Command.Long = "Cluster commands enable actions on Temporal Clusters.\n\nCluster commands follow this syntax: `temporal operator cluster [command] [command options]`" + s.Command.Long = "Perform operator actions on Temporal Services (also known as Clusters).\n\n```\ntemporal operator cluster [subcommand] [options]\n```\n\nFor example to check Service/Cluster health:\n\n```\ntemporal operator cluster health\n```" } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalOperatorClusterDescribeCommand(cctx, &s).Command) @@ -442,14 +458,14 @@ func NewTemporalOperatorClusterDescribeCommand(cctx *CommandContext, parent *Tem s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "describe [flags]" - s.Command.Short = "Describe a cluster" + s.Command.Short = "Show Temporal Cluster information" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster describe\x1b[0m command shows information about the Cluster." + s.Command.Long = "View information about a Temporal Cluster (Service), including Cluster Name,\npersistence store, and visibility store. Add \x1b[1m--detail\x1b[0m for additional info:\n\n\x1b[1mtemporal operator cluster describe [--detail]\x1b[0m" } else { - s.Command.Long = "`temporal operator cluster describe` command shows information about the Cluster." + s.Command.Long = "View information about a Temporal Cluster (Service), including Cluster Name,\npersistence store, and visibility store. Add `--detail` for additional info:\n\n```\ntemporal operator cluster describe [--detail]\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().BoolVar(&s.Detail, "detail", false, "Prints extra details.") + s.Command.Flags().BoolVar(&s.Detail, "detail", false, "Show history shard count and Cluster/Service version information.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -468,11 +484,11 @@ func NewTemporalOperatorClusterHealthCommand(cctx *CommandContext, parent *Tempo s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "health [flags]" - s.Command.Short = "Checks the health of a cluster" + s.Command.Short = "Check Temporal Service health" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster health\x1b[0m command checks the health of the Frontend Service." + s.Command.Long = "View information about the health of a Temporal Service:\n\n\x1b[1mtemporal operator cluster health\x1b[0m" } else { - s.Command.Long = "`temporal operator cluster health` command checks the health of the Frontend Service." + s.Command.Long = "View information about the health of a Temporal Service:\n\n```\ntemporal operator cluster health\n```" } s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { @@ -494,14 +510,14 @@ func NewTemporalOperatorClusterListCommand(cctx *CommandContext, parent *Tempora s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "list [flags]" - s.Command.Short = "List all clusters" + s.Command.Short = "Show Temporal Clusters" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster list\x1b[0m command prints a list of all remote Clusters on the system." + s.Command.Long = "Print a list of remote Temporal Clusters (Services) registered to the local\nService. Report details include the Cluster's name, ID, address, History Shard\ncount, Failover version, and availability:\n\n\x1b[1mtemporal operator cluster list [--limit max-count]\x1b[0m" } else { - s.Command.Long = "`temporal operator cluster list` command prints a list of all remote Clusters on the system." + s.Command.Long = "Print a list of remote Temporal Clusters (Services) registered to the local\nService. Report details include the Cluster's name, ID, address, History Shard\ncount, Failover version, and availability:\n\n```\ntemporal operator cluster list [--limit max-count]\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Limit the number of items to print.") + s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Maximum number of Clusters to display.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -521,14 +537,14 @@ func NewTemporalOperatorClusterRemoveCommand(cctx *CommandContext, parent *Tempo s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "remove [flags]" - s.Command.Short = "Remove a cluster" + s.Command.Short = "Remove a Temporal Cluster" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster remove\x1b[0m command removes a remote Cluster from the system." + s.Command.Long = "Remove a registered remote Temporal Cluster (Service) from the local Service.\n\n\x1b[1mtemporal operator cluster remove \\\n --name YourClusterName\x1b[0m" } else { - s.Command.Long = "`temporal operator cluster remove` command removes a remote Cluster from the system." + s.Command.Long = "Remove a registered remote Temporal Cluster (Service) from the local Service.\n\n```\ntemporal operator cluster remove \\\n --name YourClusterName\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.Name, "name", "", "Name of cluster. Required.") + s.Command.Flags().StringVar(&s.Name, "name", "", "Cluster/Service name. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "name") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -548,11 +564,11 @@ func NewTemporalOperatorClusterSystemCommand(cctx *CommandContext, parent *Tempo s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "system [flags]" - s.Command.Short = "Provide system info" + s.Command.Short = "Show Temporal Cluster info" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster system\x1b[0m command provides information about the system the Cluster is running on. This information can be used to diagnose problems occurring in the Temporal Server." + s.Command.Long = "Show Temporal Server information for Temporal Clusters (Service): Server\nversion, scheduling support, and more. This information helps diagnose\nproblems with the Temporal Server.\n\nThe command defaults to the local Service. Otherwise, use the\n\x1b[1m--frontend-address\x1b[0m option to specify a Cluster (Service) endpoint:\n\n\x1b[1mtemporal operator cluster system \\\n --frontend-address \"YourRemoteEndpoint:YourRemotePort\"\x1b[0m" } else { - s.Command.Long = "`temporal operator cluster system` command provides information about the system the Cluster is running on. This information can be used to diagnose problems occurring in the Temporal Server." + s.Command.Long = "Show Temporal Server information for Temporal Clusters (Service): Server\nversion, scheduling support, and more. This information helps diagnose\nproblems with the Temporal Server.\n\nThe command defaults to the local Service. Otherwise, use the\n`--frontend-address` option to specify a Cluster (Service) endpoint:\n\n```\ntemporal operator cluster system \\\n --frontend-address \"YourRemoteEndpoint:YourRemotePort\"\n```" } s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { @@ -575,16 +591,16 @@ func NewTemporalOperatorClusterUpsertCommand(cctx *CommandContext, parent *Tempo s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "upsert [flags]" - s.Command.Short = "Add a remote" + s.Command.Short = "Add/update a Temporal Cluster" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster upsert\x1b[0m command allows the user to add or update a remote Cluster." + s.Command.Long = "Add, remove, or update a registered (\"remote\") Temporal Cluster (Service).\n\n\x1b[1mtemporal operator cluster upsert [options]\x1b[0m\n\nFor example:\n\n\x1b[1mtemporal operator cluster upsert \\\n --frontend-address \"YourRemoteEndpoint:YourRemotePort\"\n --enable-connection false\x1b[0m" } else { - s.Command.Long = "`temporal operator cluster upsert` command allows the user to add or update a remote Cluster." + s.Command.Long = "Add, remove, or update a registered (\"remote\") Temporal Cluster (Service).\n\n```\ntemporal operator cluster upsert [options]\n```\n\nFor example:\n\n```\ntemporal operator cluster upsert \\\n --frontend-address \"YourRemoteEndpoint:YourRemotePort\"\n --enable-connection false\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.FrontendAddress, "frontend-address", "", "IP address to bind the frontend service to. Required.") + s.Command.Flags().StringVar(&s.FrontendAddress, "frontend-address", "", "Remote endpoint. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "frontend-address") - s.Command.Flags().BoolVar(&s.EnableConnection, "enable-connection", false, "enable cross cluster connection.") + s.Command.Flags().BoolVar(&s.EnableConnection, "enable-connection", false, "Set the connection to \"enabled\".") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -602,11 +618,11 @@ func NewTemporalOperatorNamespaceCommand(cctx *CommandContext, parent *TemporalO var s TemporalOperatorNamespaceCommand s.Parent = parent s.Command.Use = "namespace" - s.Command.Short = "Operations performed on Namespaces." + s.Command.Short = "Namespace operations" if hasHighlighting { - s.Command.Long = "Namespace commands perform operations on Namespaces contained in the Temporal Cluster.\n\nCluster commands follow this syntax: \x1b[1mtemporal operator namespace [command] [command options]\x1b[0m" + s.Command.Long = "Manage Temporal Cluster (Service) Namespaces:\n\n\x1b[1mtemporal operator namespace [command] [command options]\x1b[0m\n\nFor example:\n\n\x1b[1mtemporal operator namespace create \\\n --namespace YourNewNamespaceName\x1b[0m" } else { - s.Command.Long = "Namespace commands perform operations on Namespaces contained in the Temporal Cluster.\n\nCluster commands follow this syntax: `temporal operator namespace [command] [command options]`" + s.Command.Long = "Manage Temporal Cluster (Service) Namespaces:\n\n```\ntemporal operator namespace [command] [command options]\n```\n\nFor example:\n\n```\ntemporal operator namespace create \\\n --namespace YourNewNamespaceName\n```" } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalOperatorNamespaceCreateCommand(cctx, &s).Command) @@ -638,27 +654,27 @@ func NewTemporalOperatorNamespaceCreateCommand(cctx *CommandContext, parent *Tem s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "create [flags]" - s.Command.Short = "Registers a new Namespace." + s.Command.Short = "Register a new Namespace" if hasHighlighting { - s.Command.Long = "The temporal operator namespace create command creates a new Namespace on the Server.\nNamespaces can be created on the active Cluster, or any named Cluster.\n\x1b[1mtemporal operator namespace create --cluster=MyCluster -n example-1\x1b[0m\n\nGlobal Namespaces can also be created.\n\x1b[1mtemporal operator namespace create --global -n example-2\x1b[0m\n\nOther settings, such as retention and Visibility Archival State, can be configured as needed.\nFor example, the Visibility Archive can be set on a separate URI.\n\x1b[1mtemporal operator namespace create --retention=5 --visibility-archival-state=enabled --visibility-uri=some-uri -n example-3\x1b[0m" + s.Command.Long = "Create a new Namespace on the Temporal Service:\n\n\x1b[1mtemporal operator namespace create \\\n --namespace YourNewNamespaceName \\\n [options]\x1b[0m`\n\nCreate a Namespace with multi-region data replication:\n\n\x1b[1mtemporal operator namespace create \\\n --global \\\n --namespace YourNewNamespaceName\x1b[0m\n\nConfigure settings like retention and Visibility Archival State as needed.\nFor example, the Visibility Archive can be set on a separate URI:\n\n\x1b[1mtemporal operator namespace create \\\n --retention 5d \\\n --visibility-archival-state enabled \\\n --visibility-uri YourURI \\\n --namespace YourNewNamespaceName\x1b[0m\n\nNote: URI values for archival states can't be changed once enabled." } else { - s.Command.Long = "The temporal operator namespace create command creates a new Namespace on the Server.\nNamespaces can be created on the active Cluster, or any named Cluster.\n`temporal operator namespace create --cluster=MyCluster -n example-1`\n\nGlobal Namespaces can also be created.\n`temporal operator namespace create --global -n example-2`\n\nOther settings, such as retention and Visibility Archival State, can be configured as needed.\nFor example, the Visibility Archive can be set on a separate URI.\n`temporal operator namespace create --retention=5 --visibility-archival-state=enabled --visibility-uri=some-uri -n example-3`" + s.Command.Long = "Create a new Namespace on the Temporal Service:\n\n```\ntemporal operator namespace create \\\n --namespace YourNewNamespaceName \\\n [options]\n````\n\nCreate a Namespace with multi-region data replication:\n\n```\ntemporal operator namespace create \\\n --global \\\n --namespace YourNewNamespaceName\n```\n\nConfigure settings like retention and Visibility Archival State as needed.\nFor example, the Visibility Archive can be set on a separate URI:\n\n```\ntemporal operator namespace create \\\n --retention 5d \\\n --visibility-archival-state enabled \\\n --visibility-uri YourURI \\\n --namespace YourNewNamespaceName\n```\n\nNote: URI values for archival states can't be changed once enabled." } s.Command.Args = cobra.MaximumNArgs(1) - s.Command.Flags().StringVar(&s.ActiveCluster, "active-cluster", "", "Active cluster name.") - s.Command.Flags().StringArrayVar(&s.Cluster, "cluster", nil, "Cluster names.") - s.Command.Flags().StringArrayVar(&s.Data, "data", nil, "Namespace data in key=value format. Use JSON for values.") + s.Command.Flags().StringVar(&s.ActiveCluster, "active-cluster", "", "Active Cluster (Service) name.") + s.Command.Flags().StringArrayVar(&s.Cluster, "cluster", nil, "Cluster (Service) names for Namespace creation. Can be passed multiple times.") + s.Command.Flags().StringArrayVar(&s.Data, "data", nil, "Namespace data as `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: 'YourKey={\"your\": \"value\"}'. Can be passed multiple times.") s.Command.Flags().StringVar(&s.Description, "description", "", "Namespace description.") s.Command.Flags().StringVar(&s.Email, "email", "", "Owner email.") - s.Command.Flags().BoolVar(&s.Global, "global", false, "Whether the namespace is a global namespace.") + s.Command.Flags().BoolVar(&s.Global, "global", false, "Enable multi-region data replication.") s.HistoryArchivalState = NewStringEnum([]string{"disabled", "enabled"}, "disabled") s.Command.Flags().Var(&s.HistoryArchivalState, "history-archival-state", "History archival state. Accepted values: disabled, enabled.") - s.Command.Flags().StringVar(&s.HistoryUri, "history-uri", "", "Optionally specify history archival URI (cannot be changed after first time archival is enabled).") + s.Command.Flags().StringVar(&s.HistoryUri, "history-uri", "", "Archive history to this `URI`. Once enabled, can't be changed.") s.Retention = Duration(259200000 * time.Millisecond) - s.Command.Flags().Var(&s.Retention, "retention", "Length of time a closed Workflow is preserved before deletion.") + s.Command.Flags().Var(&s.Retention, "retention", "Time to preserve closed Workflows before deletion.") s.VisibilityArchivalState = NewStringEnum([]string{"disabled", "enabled"}, "disabled") s.Command.Flags().Var(&s.VisibilityArchivalState, "visibility-archival-state", "Visibility archival state. Accepted values: disabled, enabled.") - s.Command.Flags().StringVar(&s.VisibilityUri, "visibility-uri", "", "Optionally specify visibility archival URI (cannot be changed after first time archival is enabled).") + s.Command.Flags().StringVar(&s.VisibilityUri, "visibility-uri", "", "Archive visibility data to this `URI`. Once enabled, can't be changed.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -678,10 +694,14 @@ func NewTemporalOperatorNamespaceDeleteCommand(cctx *CommandContext, parent *Tem s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "delete [flags] [namespace]" - s.Command.Short = "Deletes an existing Namespace." - s.Command.Long = "The temporal operator namespace delete command deletes a given Namespace from the system." + s.Command.Short = "Delete a Namespace" + if hasHighlighting { + s.Command.Long = "Removes a Namespace from the Service.\n\n\x1b[1mtemporal operator namespace delete [options]\x1b[0m\n\nFor example:\n\n\x1b[1mtemporal operator namespace delete \\\n --namespace YourNamespaceName\x1b[0m" + } else { + s.Command.Long = "Removes a Namespace from the Service.\n\n```\ntemporal operator namespace delete [options]\n```\n\nFor example:\n\n```\ntemporal operator namespace delete \\\n --namespace YourNamespaceName\n```" + } s.Command.Args = cobra.MaximumNArgs(1) - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Confirm prompt to perform deletion.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Request confirmation before deletion.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -701,11 +721,11 @@ func NewTemporalOperatorNamespaceDescribeCommand(cctx *CommandContext, parent *T s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "describe [flags] [namespace]" - s.Command.Short = "Describe a Namespace by its name or ID." + s.Command.Short = "Describe a Namespace" if hasHighlighting { - s.Command.Long = "The temporal operator namespace describe command provides Namespace information.\nNamespaces are identified either by Namespace ID or by name.\n\n\x1b[1mtemporal operator namespace describe --namespace-id=some-namespace-id\x1b[0m\n\x1b[1mtemporal operator namespace describe -n example-namespace-name\x1b[0m" + s.Command.Long = "Provide long-form information about a Namespace identified by its ID or name:\n\n\x1b[1mtemporal operator namespace describe \\\n --namespace-id YourNamespaceId\x1b[0m\n\nor\n\n\x1b[1mtemporal operator namespace describe \\\n --namespace YourNamespaceName\x1b[0m" } else { - s.Command.Long = "The temporal operator namespace describe command provides Namespace information.\nNamespaces are identified either by Namespace ID or by name.\n\n`temporal operator namespace describe --namespace-id=some-namespace-id`\n`temporal operator namespace describe -n example-namespace-name`" + s.Command.Long = "Provide long-form information about a Namespace identified by its ID or name:\n\n```\ntemporal operator namespace describe \\\n --namespace-id YourNamespaceId\n```\n\nor\n\n```\ntemporal operator namespace describe \\\n --namespace YourNamespaceName\n```" } s.Command.Args = cobra.MaximumNArgs(1) s.Command.Flags().StringVar(&s.NamespaceId, "namespace-id", "", "Namespace ID.") @@ -727,8 +747,12 @@ func NewTemporalOperatorNamespaceListCommand(cctx *CommandContext, parent *Tempo s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "list [flags]" - s.Command.Short = "List all Namespaces." - s.Command.Long = "The temporal operator namespace list command lists all Namespaces on the Server." + s.Command.Short = "List Namespaces" + if hasHighlighting { + s.Command.Long = "Display a detailed listing for all Namespaces on the Service:\n\n\x1b[1mtemporal operator namespace list\x1b[0m" + } else { + s.Command.Long = "Display a detailed listing for all Namespaces on the Service:\n\n```\ntemporal operator namespace list\n```" + } s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -759,27 +783,27 @@ func NewTemporalOperatorNamespaceUpdateCommand(cctx *CommandContext, parent *Tem s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "update [flags]" - s.Command.Short = "Updates a Namespace." + s.Command.Short = "Update a Namespace" if hasHighlighting { - s.Command.Long = "The temporal operator namespace update command updates a Namespace.\n\nNamespaces can be assigned a different active Cluster.\n\x1b[1mtemporal operator namespace update -n namespace --active-cluster=NewActiveCluster\x1b[0m\n\nNamespaces can also be promoted to global Namespaces.\n\x1b[1mtemporal operator namespace update -n namespace --promote-global\x1b[0m\n\nAny Archives that were previously enabled or disabled can be changed through this command.\nHowever, URI values for archival states cannot be changed after the states are enabled.\n\x1b[1mtemporal operator namespace update -n namespace --history-archival-state=enabled --visibility-archival-state=disabled\x1b[0m" + s.Command.Long = "Update a Namespace using properties you specify.\n\n\x1b[1mtemporal operator namespace update [options]\x1b[0m\n\nAssign a Namespace's active Cluster (Service):\n\n\x1b[1mtemporal operator namespace update \\\n --namespace YourNamespaceName \\\n --active-cluster NewActiveCluster\x1b[0m\n\nPromote a Namespace for multi-region data replication:\n\n\x1b[1mtemporal operator namespace update \\\n --namespace YourNamespaceName \\\n --promote-global\x1b[0m\n\nYou may update archives that were previously enabled or disabled. Note: URI\nvalues for archival states can't be changed once enabled.\n\n\x1b[1mtemporal operator namespace update \\\n --namespace YourNamespaceName \\\n --history-archival-state enabled \\\n --visibility-archival-state disabled\x1b[0m" } else { - s.Command.Long = "The temporal operator namespace update command updates a Namespace.\n\nNamespaces can be assigned a different active Cluster.\n`temporal operator namespace update -n namespace --active-cluster=NewActiveCluster`\n\nNamespaces can also be promoted to global Namespaces.\n`temporal operator namespace update -n namespace --promote-global`\n\nAny Archives that were previously enabled or disabled can be changed through this command.\nHowever, URI values for archival states cannot be changed after the states are enabled.\n`temporal operator namespace update -n namespace --history-archival-state=enabled --visibility-archival-state=disabled`" + s.Command.Long = "Update a Namespace using properties you specify.\n\n```\ntemporal operator namespace update [options]\n```\n\nAssign a Namespace's active Cluster (Service):\n\n```\ntemporal operator namespace update \\\n --namespace YourNamespaceName \\\n --active-cluster NewActiveCluster\n```\n\nPromote a Namespace for multi-region data replication:\n\n```\ntemporal operator namespace update \\\n --namespace YourNamespaceName \\\n --promote-global\n```\n\nYou may update archives that were previously enabled or disabled. Note: URI\nvalues for archival states can't be changed once enabled.\n\n```\ntemporal operator namespace update \\\n --namespace YourNamespaceName \\\n --history-archival-state enabled \\\n --visibility-archival-state disabled\n```" } s.Command.Args = cobra.MaximumNArgs(1) - s.Command.Flags().StringVar(&s.ActiveCluster, "active-cluster", "", "Active cluster name.") - s.Command.Flags().StringArrayVar(&s.Cluster, "cluster", nil, "Cluster names.") - s.Command.Flags().StringArrayVar(&s.Data, "data", nil, "Namespace data in key=value format. Use JSON for values.") + s.Command.Flags().StringVar(&s.ActiveCluster, "active-cluster", "", "Active Cluster (Service) name.") + s.Command.Flags().StringArrayVar(&s.Cluster, "cluster", nil, "Cluster (Service) names.") + s.Command.Flags().StringArrayVar(&s.Data, "data", nil, "Namespace data as `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: 'YourKey={\"your\": \"value\"}'. Can be passed multiple times.") s.Command.Flags().StringVar(&s.Description, "description", "", "Namespace description.") s.Command.Flags().StringVar(&s.Email, "email", "", "Owner email.") - s.Command.Flags().BoolVar(&s.PromoteGlobal, "promote-global", false, "Promote local namespace to global namespace.") + s.Command.Flags().BoolVar(&s.PromoteGlobal, "promote-global", false, "Enable multi-region data replication.") s.HistoryArchivalState = NewStringEnum([]string{"disabled", "enabled"}, "") s.Command.Flags().Var(&s.HistoryArchivalState, "history-archival-state", "History archival state. Accepted values: disabled, enabled.") - s.Command.Flags().StringVar(&s.HistoryUri, "history-uri", "", "Optionally specify history archival URI (cannot be changed after first time archival is enabled).") + s.Command.Flags().StringVar(&s.HistoryUri, "history-uri", "", "Archive history to this `URI`. Once enabled, can't be changed.") s.Retention = 0 - s.Command.Flags().Var(&s.Retention, "retention", "Length of time a closed Workflow is preserved before deletion.") + s.Command.Flags().Var(&s.Retention, "retention", "Length of time a closed Workflow is preserved before deletion") s.VisibilityArchivalState = NewStringEnum([]string{"disabled", "enabled"}, "") s.Command.Flags().Var(&s.VisibilityArchivalState, "visibility-archival-state", "Visibility archival state. Accepted values: disabled, enabled.") - s.Command.Flags().StringVar(&s.VisibilityUri, "visibility-uri", "", "Optionally specify visibility archival URI (cannot be changed after first time archival is enabled).") + s.Command.Flags().StringVar(&s.VisibilityUri, "visibility-uri", "", "Archive visibility data to this `URI`. Once enabled, can't be changed.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -797,8 +821,12 @@ func NewTemporalOperatorSearchAttributeCommand(cctx *CommandContext, parent *Tem var s TemporalOperatorSearchAttributeCommand s.Parent = parent s.Command.Use = "search-attribute" - s.Command.Short = "Operations applying to Search Attributes" - s.Command.Long = "Search Attribute commands enable operations for the creation, listing, and removal of Search Attributes." + s.Command.Short = "Search Attribute operations" + if hasHighlighting { + s.Command.Long = "Create, list, or remove Search Attributes fields stored in a Workflow\nExecution's metadata:\n\n\x1b[1mtemporal operator search-attribute create \\\n --name YourAttributeName \\\n --type Keyword\x1b[0m\n\nSupported types include: Text, Keyword, Int, Double, Bool, Datetime, and\nKeywordList." + } else { + s.Command.Long = "Create, list, or remove Search Attributes fields stored in a Workflow\nExecution's metadata:\n\n```\ntemporal operator search-attribute create \\\n --name YourAttributeName \\\n --type Keyword\n```\n\nSupported types include: Text, Keyword, Int, Double, Bool, Datetime, and\nKeywordList." + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalOperatorSearchAttributeCreateCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalOperatorSearchAttributeListCommand(cctx, &s).Command) @@ -818,11 +846,11 @@ func NewTemporalOperatorSearchAttributeCreateCommand(cctx *CommandContext, paren s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "create [flags]" - s.Command.Short = "Adds one or more custom Search Attributes" + s.Command.Short = "Add custom Search Attributes" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator search-attribute create\x1b[0m command adds one or more custom Search Attributes." + s.Command.Long = "Add one or more custom Search Attributes:\n\n\x1b[1mtemporal operator search-attribute create \\\n --name YourAttributeName \\\n --type Keyword\x1b[0m" } else { - s.Command.Long = "`temporal operator search-attribute create` command adds one or more custom Search Attributes." + s.Command.Long = "Add one or more custom Search Attributes:\n\n```\ntemporal operator search-attribute create \\\n --name YourAttributeName \\\n --type Keyword\n```" } s.Command.Args = cobra.NoArgs s.Command.Flags().StringArrayVar(&s.Name, "name", nil, "Search Attribute name. Required.") @@ -847,11 +875,11 @@ func NewTemporalOperatorSearchAttributeListCommand(cctx *CommandContext, parent s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "list [flags]" - s.Command.Short = "Lists all Search Attributes that can be used in list Workflow Queries" + s.Command.Short = "List Search Attributes" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator search-attribute list\x1b[0m displays a list of all Search Attributes." + s.Command.Long = "Display a list of active Search Attributes that can be assigned or used with\nWorkflow Queries. You can manage this list and add attributes as needed:\n\n\x1b[1mtemporal operator search-attribute list\x1b[0m" } else { - s.Command.Long = "`temporal operator search-attribute list` displays a list of all Search Attributes." + s.Command.Long = "Display a list of active Search Attributes that can be assigned or used with\nWorkflow Queries. You can manage this list and add attributes as needed:\n\n```\ntemporal operator search-attribute list\n```" } s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { @@ -874,16 +902,16 @@ func NewTemporalOperatorSearchAttributeRemoveCommand(cctx *CommandContext, paren s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "remove [flags]" - s.Command.Short = "Removes custom search attribute metadata only" + s.Command.Short = "Remove custom Search Attributes" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator search-attribute remove\x1b[0m command removes custom Search Attribute metadata." + s.Command.Long = "Remove custom Search Attributes from the options that can be assigned or used\nwith Workflow Queries.\n\n\x1b[1mtemporal operator search-attribute remove \\\n --name YourAttributeName\x1b[0m\n\nRemove attributes without confirmation:\n\n\x1b[1mtemporal operator search-attribute remove \\\n --name YourAttributeName \\\n --yes\x1b[0m" } else { - s.Command.Long = "`temporal operator search-attribute remove` command removes custom Search Attribute metadata." + s.Command.Long = "Remove custom Search Attributes from the options that can be assigned or used\nwith Workflow Queries.\n\n```\ntemporal operator search-attribute remove \\\n --name YourAttributeName\n```\n\nRemove attributes without confirmation:\n\n```\ntemporal operator search-attribute remove \\\n --name YourAttributeName \\\n --yes\n```" } s.Command.Args = cobra.NoArgs s.Command.Flags().StringArrayVar(&s.Name, "name", nil, "Search Attribute name. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "name") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Confirm prompt to perform deletion.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm removal.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -902,8 +930,12 @@ func NewTemporalScheduleCommand(cctx *CommandContext, parent *TemporalCommand) * var s TemporalScheduleCommand s.Parent = parent s.Command.Use = "schedule" - s.Command.Short = "Perform operations on Schedules." - s.Command.Long = "Schedule commands allow the user to create, use, and update Schedules.\nSchedules allow starting Workflow Execution at regular times." + s.Command.Short = "Perform operations on Schedules" + if hasHighlighting { + s.Command.Long = "Create, use, and update Schedules that allow Workflow Executions to be created\nat specified times:\n\n\x1b[1mtemporal schedule [commands] [options]\x1b[0m\n\nFor example:\n\n\x1b[1mtemporal schedule describe \\\n --schedule-id \"YourScheduleId\"\x1b[0m" + } else { + s.Command.Long = "Create, use, and update Schedules that allow Workflow Executions to be created\nat specified times:\n\n```\ntemporal schedule [commands] [options]\n```\n\nFor example:\n\n```\ntemporal schedule describe \\\n --schedule-id \"YourScheduleId\"\n```" + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalScheduleBackfillCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalScheduleCreateCommand(cctx, &s).Command) @@ -931,7 +963,7 @@ type ScheduleIdOptions struct { } func (v *ScheduleIdOptions) buildFlags(cctx *CommandContext, f *pflag.FlagSet) { - f.StringVarP(&v.ScheduleId, "schedule-id", "s", "", "Schedule id. Required.") + f.StringVarP(&v.ScheduleId, "schedule-id", "s", "", "Schedule ID. Required.") _ = cobra.MarkFlagRequired(f, "schedule-id") } @@ -949,11 +981,11 @@ func NewTemporalScheduleBackfillCommand(cctx *CommandContext, parent *TemporalSc s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "backfill [flags]" - s.Command.Short = "Backfills a past time range of actions." + s.Command.Short = "Backfill past actions" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal schedule backfill\x1b[0m command runs the Actions that would have been run in a given time\ninterval, all at once.\n\n You can use backfill to fill in Workflow Runs from a time period when the Schedule was paused, from\nbefore the Schedule was created, from the future, or to re-process an interval that was processed.\n\nSchedule backfills require a Schedule ID, along with the time in which to run the Schedule. You can\noptionally override the overlap policy. It usually only makes sense to run backfills with either\n\x1b[1mBufferAll\x1b[0m or \x1b[1mAllowAll\x1b[0m (other policies will only let one or two runs actually happen).\n\nExample:\n\n\x1b[1m temporal schedule backfill \\\n --schedule-id 'your-schedule-id' \\\n --overlap-policy BufferAll \\\n --start-time 2022-05-01T00:00:00Z \\\n --end-time 2022-05-31T23:59:59Z\x1b[0m" + s.Command.Long = "Batch-execute actions that would have run during a specified time interval.\nUse this command to fill in Workflow runs from when a Schedule was paused,\nbefore a Schedule was created, from the future, or to re-process a previously\nexecuted interval.\n\nBackfills require a Schedule ID and the time period covered by the request.\nIt's best to use the \x1b[1mBufferAll\x1b[0m or \x1b[1mAllowAll\x1b[0m policies to avoid conflicts\nand ensure no Workflow Executions are skipped.\n\nFor example:\n\n\x1b[1m temporal schedule backfill \\\n --schedule-id \"YourScheduleId\" \\\n --start-time \"2022-05-01T00:00:00Z\" \\\n --end-time \"2022-05-31T23:59:59Z\" \\\n --overlap-policy BufferAll\x1b[0m\n\nThe policies include:\n\n* **AllowAll**: Allow unlimited concurrent Workflow Executions. This\n significantly speeds up the backfilling process on systems that support\n concurrency. You must ensure running Workflow Executions do not interfere\n with each other.\n* **BufferAll**: Buffer all incoming Workflow Executions while waiting for\n the running Workflow Execution to complete.\n* **Skip**: If a previous Workflow Execution is still running, discard new\n Workflow Executions.\n* **BufferOne**: Same as 'Skip' but buffer a single Workflow Execution to be\n run after the previous Execution completes. Discard other Workflow\n Executions.\n* **CancelOther**: Cancel the running Workflow Execution and replace it with\n the incoming new Workflow Execution.\n* **TerminateOther**: Terminate the running Workflow Execution and replace\n it with the incoming new Workflow Execution." } else { - s.Command.Long = "The `temporal schedule backfill` command runs the Actions that would have been run in a given time\ninterval, all at once.\n\n You can use backfill to fill in Workflow Runs from a time period when the Schedule was paused, from\nbefore the Schedule was created, from the future, or to re-process an interval that was processed.\n\nSchedule backfills require a Schedule ID, along with the time in which to run the Schedule. You can\noptionally override the overlap policy. It usually only makes sense to run backfills with either\n`BufferAll` or `AllowAll` (other policies will only let one or two runs actually happen).\n\nExample:\n\n```\n temporal schedule backfill \\\n --schedule-id 'your-schedule-id' \\\n --overlap-policy BufferAll \\\n --start-time 2022-05-01T00:00:00Z \\\n --end-time 2022-05-31T23:59:59Z\n```" + s.Command.Long = "Batch-execute actions that would have run during a specified time interval.\nUse this command to fill in Workflow runs from when a Schedule was paused,\nbefore a Schedule was created, from the future, or to re-process a previously\nexecuted interval.\n\nBackfills require a Schedule ID and the time period covered by the request.\nIt's best to use the `BufferAll` or `AllowAll` policies to avoid conflicts\nand ensure no Workflow Executions are skipped.\n\nFor example:\n\n```\n temporal schedule backfill \\\n --schedule-id \"YourScheduleId\" \\\n --start-time \"2022-05-01T00:00:00Z\" \\\n --end-time \"2022-05-31T23:59:59Z\" \\\n --overlap-policy BufferAll\n```\n\nThe policies include:\n\n* **AllowAll**: Allow unlimited concurrent Workflow Executions. This\n significantly speeds up the backfilling process on systems that support\n concurrency. You must ensure running Workflow Executions do not interfere\n with each other.\n* **BufferAll**: Buffer all incoming Workflow Executions while waiting for\n the running Workflow Execution to complete.\n* **Skip**: If a previous Workflow Execution is still running, discard new\n Workflow Executions.\n* **BufferOne**: Same as 'Skip' but buffer a single Workflow Execution to be\n run after the previous Execution completes. Discard other Workflow\n Executions.\n* **CancelOther**: Cancel the running Workflow Execution and replace it with\n the incoming new Workflow Execution.\n* **TerminateOther**: Terminate the running Workflow Execution and replace\n it with the incoming new Workflow Execution." } s.Command.Args = cobra.NoArgs s.OverlapPolicyOptions.buildFlags(cctx, s.Command.Flags()) @@ -988,22 +1020,22 @@ type ScheduleConfigurationOptions struct { } func (v *ScheduleConfigurationOptions) buildFlags(cctx *CommandContext, f *pflag.FlagSet) { - f.StringArrayVar(&v.Calendar, "calendar", nil, "Calendar specification in JSON, e.g. `{\"dayOfWeek\":\"Fri\",\"hour\":\"17\",\"minute\":\"5\"}`.") + f.StringArrayVar(&v.Calendar, "calendar", nil, "Calendar specification in JSON. For example: `{\"dayOfWeek\":\"Fri\",\"hour\":\"17\",\"minute\":\"5\"}`.") v.CatchupWindow = 0 - f.Var(&v.CatchupWindow, "catchup-window", "Maximum allowed catch-up time if server is down.") - f.StringArrayVar(&v.Cron, "cron", nil, "Calendar spec in cron string format, e.g. `3 11 * * Fri`.") - f.Var(&v.EndTime, "end-time", "Overall schedule end time.") - f.StringArrayVar(&v.Interval, "interval", nil, "Interval duration, e.g. 90m, or 90m/13m to include phase offset.") + f.Var(&v.CatchupWindow, "catchup-window", "Maximum catch-up time for when the Service is unavailable.") + f.StringArrayVar(&v.Cron, "cron", nil, "Calendar specification in cron string format. For example: `\"30 12 * * Fri\"`.") + f.Var(&v.EndTime, "end-time", "Schedule end time") + f.StringArrayVar(&v.Interval, "interval", nil, "Interval duration. For example, 90m, or 60m/15m to include phase offset.") v.Jitter = 0 - f.Var(&v.Jitter, "jitter", "Per-action jitter range.") - f.StringVar(&v.Notes, "notes", "", "Initial value of notes field.") - f.BoolVar(&v.Paused, "paused", false, "Initial value of paused state.") - f.BoolVar(&v.PauseOnFailure, "pause-on-failure", false, "Pause schedule after any workflow failure.") - f.IntVar(&v.RemainingActions, "remaining-actions", 0, "Total number of actions allowed. Zero (default) means unlimited.") - f.Var(&v.StartTime, "start-time", "Overall schedule start time.") - f.StringVar(&v.TimeZone, "time-zone", "", "Time zone to interpret all calendar specs in (IANA name).") - f.StringArrayVar(&v.ScheduleSearchAttribute, "schedule-search-attribute", nil, "Search Attribute for the _schedule_ in key=value format. Use valid JSON formats for value.") - f.StringArrayVar(&v.ScheduleMemo, "schedule-memo", nil, "Memo for the _schedule_ in key=value format. Use valid JSON formats for value.") + f.Var(&v.Jitter, "jitter", "Max difference in time from the specification. Vary the start time randomly within this amount.") + f.StringVar(&v.Notes, "notes", "", "Initial notes field value.") + f.BoolVar(&v.Paused, "paused", false, "Pause the Schedule immediately on creation.") + f.BoolVar(&v.PauseOnFailure, "pause-on-failure", false, "Pause schedule after Workflow failures.") + f.IntVar(&v.RemainingActions, "remaining-actions", 0, "Total allowed actions. Default is zero (unlimited).") + f.Var(&v.StartTime, "start-time", "Schedule start time.") + f.StringVar(&v.TimeZone, "time-zone", "", "Interpret calendar specs with the `TZ` time zone. For a list of time zones, see: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.") + f.StringArrayVar(&v.ScheduleSearchAttribute, "schedule-search-attribute", nil, "Set schedule Search Attributes using `KEY=\"VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: 'YourKey={\"your\": \"value\"}'. Can be passed multiple times.") + f.StringArrayVar(&v.ScheduleMemo, "schedule-memo", nil, "Set a schedule memo using `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: 'YourKey={\"your\": \"value\"}'. Can be passed multiple times.") } type TemporalScheduleCreateCommand struct { @@ -1021,11 +1053,11 @@ func NewTemporalScheduleCreateCommand(cctx *CommandContext, parent *TemporalSche s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "create [flags]" - s.Command.Short = "Create a new Schedule." + s.Command.Short = "Create a new Schedule" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal schedule create\x1b[0m command creates a new Schedule.\n\nExample:\n\n\x1b[1m temporal schedule create \\\n --schedule-id 'your-schedule-id' \\\n --calendar '{\"dayOfWeek\":\"Fri\",\"hour\":\"3\",\"minute\":\"11\"}' \\\n --workflow-id 'your-base-workflow-id' \\\n --task-queue 'your-task-queue' \\\n --workflow-type 'YourWorkflowType'\x1b[0m\n\nAny combination of \x1b[1m--calendar\x1b[0m, \x1b[1m--interval\x1b[0m, and \x1b[1m--cron\x1b[0m is supported.\nActions will be executed at any time specified in the Schedule." + s.Command.Long = "Create a new Schedule on the Temporal Service. A Schedule automatically starts\nnew Workflow Executions at the times you specify.\n\nFor example:\n\n\x1b[1m temporal schedule create \\\n --schedule-id \"YourScheduleId\" \\\n --calendar '{\"dayOfWeek\":\"Fri\",\"hour\":\"3\",\"minute\":\"30\"}' \\\n --workflow-id YourBaseWorkflowIdName \\\n --task-queue YourTaskQueue \\\n --workflow-type YourWorkflowType\x1b[0m\n\nSchedules support any combination of \x1b[1m--calendar\x1b[0m, \x1b[1m--interval\x1b[0m, and \x1b[1m--cron\x1b[0m:\n\n* Shorthand \x1b[1m--interval\x1b[0m strings.\n For example: 45m (every 45 minutes) or 6h/5h (every 6 hours, at the top of\n the 5th hour).\n* JSON \x1b[1m--calendar\x1b[0m, as in the preceding example.\n* Unix-style \x1b[1m--cron\x1b[0m strings and robfig declarations\n (@daily/@weekly/@every X/etc).\n For example, every Friday at 12:30 PM: \x1b[1m30 12 * * Fri\x1b[0m." } else { - s.Command.Long = "The `temporal schedule create` command creates a new Schedule.\n\nExample:\n\n```\n temporal schedule create \\\n --schedule-id 'your-schedule-id' \\\n --calendar '{\"dayOfWeek\":\"Fri\",\"hour\":\"3\",\"minute\":\"11\"}' \\\n --workflow-id 'your-base-workflow-id' \\\n --task-queue 'your-task-queue' \\\n --workflow-type 'YourWorkflowType'\n```\n\nAny combination of `--calendar`, `--interval`, and `--cron` is supported.\nActions will be executed at any time specified in the Schedule." + s.Command.Long = "Create a new Schedule on the Temporal Service. A Schedule automatically starts\nnew Workflow Executions at the times you specify.\n\nFor example:\n\n```\n temporal schedule create \\\n --schedule-id \"YourScheduleId\" \\\n --calendar '{\"dayOfWeek\":\"Fri\",\"hour\":\"3\",\"minute\":\"30\"}' \\\n --workflow-id YourBaseWorkflowIdName \\\n --task-queue YourTaskQueue \\\n --workflow-type YourWorkflowType\n```\n\nSchedules support any combination of `--calendar`, `--interval`, and `--cron`:\n\n* Shorthand `--interval` strings.\n For example: 45m (every 45 minutes) or 6h/5h (every 6 hours, at the top of\n the 5th hour).\n* JSON `--calendar`, as in the preceding example.\n* Unix-style `--cron` strings and robfig declarations\n (@daily/@weekly/@every X/etc).\n For example, every Friday at 12:30 PM: `30 12 * * Fri`." } s.Command.Args = cobra.NoArgs s.ScheduleConfigurationOptions.buildFlags(cctx, s.Command.Flags()) @@ -1052,11 +1084,11 @@ func NewTemporalScheduleDeleteCommand(cctx *CommandContext, parent *TemporalSche s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "delete [flags]" - s.Command.Short = "Deletes a Schedule." + s.Command.Short = "Remove a Schedule" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal schedule delete\x1b[0m command deletes a Schedule.\nDeleting a Schedule does not affect any Workflows started by the Schedule.\n\nIf you do also want to cancel or terminate Workflows started by a Schedule, consider using \x1b[1mtemporal\nworkflow delete\x1b[0m with the \x1b[1mTemporalScheduledById\x1b[0m Search Attribute." + s.Command.Long = "Deletes a Schedule on the front end Service:\n\n\x1b[1mtemporal schedule delete \\\n --schedule-id YourScheduleId\x1b[0m\n\nRemoving a Schedule won't affect the Workflow Executions it started that are\nstill running. To cancel or terminate these Workflow Executions, use \x1b[1mtemporal\nworkflow delete\x1b[0m with the \x1b[1mTemporalScheduledById\x1b[0m Search Attribute instead." } else { - s.Command.Long = "The `temporal schedule delete` command deletes a Schedule.\nDeleting a Schedule does not affect any Workflows started by the Schedule.\n\nIf you do also want to cancel or terminate Workflows started by a Schedule, consider using `temporal\nworkflow delete` with the `TemporalScheduledById` Search Attribute." + s.Command.Long = "Deletes a Schedule on the front end Service:\n\n```\ntemporal schedule delete \\\n --schedule-id YourScheduleId\n```\n\nRemoving a Schedule won't affect the Workflow Executions it started that are\nstill running. To cancel or terminate these Workflow Executions, use `temporal\nworkflow delete` with the `TemporalScheduledById` Search Attribute instead." } s.Command.Args = cobra.NoArgs s.ScheduleIdOptions.buildFlags(cctx, s.Command.Flags()) @@ -1079,11 +1111,11 @@ func NewTemporalScheduleDescribeCommand(cctx *CommandContext, parent *TemporalSc s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "describe [flags]" - s.Command.Short = "Get Schedule configuration and current state." + s.Command.Short = "Display Schedule state" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal schedule describe\x1b[0m command shows the current configuration of one Schedule,\nincluding information about past, current, and future Workflow Runs." + s.Command.Long = "Show a Schedule configuration, including information about past, current, and\nfuture Workflow runs:\n\n\x1b[1mtemporal schedule describe \\\n --schedule-id YourScheduleId\x1b[0m" } else { - s.Command.Long = "The `temporal schedule describe` command shows the current configuration of one Schedule,\nincluding information about past, current, and future Workflow Runs." + s.Command.Long = "Show a Schedule configuration, including information about past, current, and\nfuture Workflow runs:\n\n```\ntemporal schedule describe \\\n --schedule-id YourScheduleId\n```" } s.Command.Args = cobra.NoArgs s.ScheduleIdOptions.buildFlags(cctx, s.Command.Flags()) @@ -1107,15 +1139,15 @@ func NewTemporalScheduleListCommand(cctx *CommandContext, parent *TemporalSchedu s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "list [flags]" - s.Command.Short = "Lists Schedules." + s.Command.Short = "Display hosted Schedules" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal schedule list\x1b[0m command lists all Schedules in a namespace." + s.Command.Long = "Lists the Schedules hosted by a Namespace:\n\n\x1b[1mtemporal schedule list \\\n --namespace YourNamespace\x1b[0m" } else { - s.Command.Long = "The `temporal schedule list` command lists all Schedules in a namespace." + s.Command.Long = "Lists the Schedules hosted by a Namespace:\n\n```\ntemporal schedule list \\\n --namespace YourNamespace\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().BoolVarP(&s.Long, "long", "l", false, "Include detailed information.") - s.Command.Flags().BoolVar(&s.ReallyLong, "really-long", false, "Include even more detailed information that's not really usable in table form.") + s.Command.Flags().BoolVarP(&s.Long, "long", "l", false, "Show detailed information") + s.Command.Flags().BoolVar(&s.ReallyLong, "really-long", false, "Show extensive information in non-table form.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1138,17 +1170,17 @@ func NewTemporalScheduleToggleCommand(cctx *CommandContext, parent *TemporalSche s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "toggle [flags]" - s.Command.Short = "Pauses or unpauses a Schedule." + s.Command.Short = "Pause or unpause a Schedule" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal schedule toggle\x1b[0m command can pause and unpause a Schedule.\n\nToggling a Schedule takes a reason. The reason will be set as the \x1b[1mnotes\x1b[0m field of the Schedule,\nto help with operations communication.\n\nExamples:\n\n* \x1b[1mtemporal schedule toggle --schedule-id 'your-schedule-id' --pause --reason \"paused because the database is down\"\x1b[0m\n* \x1b[1mtemporal schedule toggle --schedule-id 'your-schedule-id' --unpause --reason \"the database is back up\"\x1b[0m" + s.Command.Long = "Pause or unpause a Schedule by passing a flag with your desired state:\n\n\x1b[1mtemporal schedule toggle \\\n --schedule-id \"YourScheduleId\" \\\n --pause \\\n --reason \"YourReason\"\x1b[0m\n\nand\n\n\x1b[1mtemporal schedule toggle\n --schedule-id \"YourScheduleId\" \\\n --unpause \\\n --reason \"YourReason\"\x1b[0m\n\nThe \x1b[1m--reason\x1b[0m text updates the Schedule's \x1b[1mnotes\x1b[0m field for operations\ncommunication. It defaults to \"(no reason provided)\" if omitted. This field is\nalso visible on the Service Web UI." } else { - s.Command.Long = "The `temporal schedule toggle` command can pause and unpause a Schedule.\n\nToggling a Schedule takes a reason. The reason will be set as the `notes` field of the Schedule,\nto help with operations communication.\n\nExamples:\n\n* `temporal schedule toggle --schedule-id 'your-schedule-id' --pause --reason \"paused because the database is down\"`\n* `temporal schedule toggle --schedule-id 'your-schedule-id' --unpause --reason \"the database is back up\"`" + s.Command.Long = "Pause or unpause a Schedule by passing a flag with your desired state:\n\n```\ntemporal schedule toggle \\\n --schedule-id \"YourScheduleId\" \\\n --pause \\\n --reason \"YourReason\"\n```\n\nand\n\n```\ntemporal schedule toggle\n --schedule-id \"YourScheduleId\" \\\n --unpause \\\n --reason \"YourReason\"\n```\n\nThe `--reason` text updates the Schedule's `notes` field for operations\ncommunication. It defaults to \"(no reason provided)\" if omitted. This field is\nalso visible on the Service Web UI." } s.Command.Args = cobra.NoArgs s.ScheduleIdOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().BoolVar(&s.Pause, "pause", false, "Pauses the schedule.") - s.Command.Flags().StringVar(&s.Reason, "reason", "\"(no reason provided)\"", "Reason for pausing/unpausing.") - s.Command.Flags().BoolVar(&s.Unpause, "unpause", false, "Pauses the schedule.") + s.Command.Flags().BoolVar(&s.Pause, "pause", false, "Pause the schedule.") + s.Command.Flags().StringVar(&s.Reason, "reason", "\"(no reason provided)\"", "Reason for pausing or unpausing a Schedule.") + s.Command.Flags().BoolVar(&s.Unpause, "unpause", false, "Unpause the schedule.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1169,8 +1201,12 @@ func NewTemporalScheduleTriggerCommand(cctx *CommandContext, parent *TemporalSch s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "trigger [flags]" - s.Command.Short = "Triggers a schedule to take an action immediately." - s.Command.Long = "" + s.Command.Short = "Immediately run a Schedule" + if hasHighlighting { + s.Command.Long = "Trigger a Schedule to run immediately:\n\n\x1b[1mtemporal schedule trigger \\\n --schedule-id \"YourScheduleId\"\x1b[0m" + } else { + s.Command.Long = "Trigger a Schedule to run immediately:\n\n```\ntemporal schedule trigger \\\n --schedule-id \"YourScheduleId\"\n```" + } s.Command.Args = cobra.NoArgs s.ScheduleIdOptions.buildFlags(cctx, s.Command.Flags()) s.OverlapPolicyOptions.buildFlags(cctx, s.Command.Flags()) @@ -1197,8 +1233,12 @@ func NewTemporalScheduleUpdateCommand(cctx *CommandContext, parent *TemporalSche s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "update [flags]" - s.Command.Short = "Updates a Schedule with a new definition." - s.Command.Long = "The temporal schedule update command updates an existing Schedule. It replaces the entire\nconfiguration of the schedule, including spec, action, and policies." + s.Command.Short = "Update Schedule details" + if hasHighlighting { + s.Command.Long = "Update an existing Schedule with new configuration details, including time\nspecifications, action, and policies:\n\n\x1b[1mtemporal schedule update \\\n --schedule-id \"YourScheduleId\" \\\n --workflow-type \"NewWorkflowType\"\x1b[0m" + } else { + s.Command.Long = "Update an existing Schedule with new configuration details, including time\nspecifications, action, and policies:\n\n```\ntemporal schedule update \\\n --schedule-id \"YourScheduleId\" \\\n --workflow-type \"NewWorkflowType\"\n```" + } s.Command.Args = cobra.NoArgs s.ScheduleConfigurationOptions.buildFlags(cctx, s.Command.Flags()) s.ScheduleIdOptions.buildFlags(cctx, s.Command.Flags()) @@ -1222,11 +1262,11 @@ func NewTemporalServerCommand(cctx *CommandContext, parent *TemporalCommand) *Te var s TemporalServerCommand s.Parent = parent s.Command.Use = "server" - s.Command.Short = "Run Temporal Server." + s.Command.Short = "Run Temporal Server" if hasHighlighting { - s.Command.Long = "Start a development version of Temporal Server:\n\n\x1b[1mtemporal server start-dev\x1b[0m" + s.Command.Long = "Run a development Temporal Server on your local system. View the Web UI for\nthe default configuration at http://localhost:8233:\n\n\x1b[1mtemporal server start-dev\x1b[0m\n\nAdd persistence for Workflow Executions across runs:\n\n\x1b[1mtemporal server start-dev \\\n --db-filename path-to-your-local-persistent-store\x1b[0m\n\nSet the port from the front-end gRPC Service (7233 default):\n\n\x1b[1mtemporal server start-dev \\\n --port 7234 \\\n --ui-port 8234 \\\n --metrics-port 57271\x1b[0m\n\nUse a custom port for the Web UI. The default is the gRPC port (7233 default)\nplus 1000 (8233):\n\n\x1b[1mtemporal server start-dev \\\n --ui-port 3000\x1b[0m" } else { - s.Command.Long = "Start a development version of Temporal Server:\n\n`temporal server start-dev`" + s.Command.Long = "Run a development Temporal Server on your local system. View the Web UI for\nthe default configuration at http://localhost:8233:\n\n```\ntemporal server start-dev\n```\n\nAdd persistence for Workflow Executions across runs:\n\n```\ntemporal server start-dev \\\n --db-filename path-to-your-local-persistent-store\n```\n\nSet the port from the front-end gRPC Service (7233 default):\n\n```\ntemporal server start-dev \\\n --port 7234 \\\n --ui-port 8234 \\\n --metrics-port 57271\n```\n\nUse a custom port for the Web UI. The default is the gRPC port (7233 default)\nplus 1000 (8233):\n\n```\ntemporal server start-dev \\\n --ui-port 3000\n```" } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalServerStartDevCommand(cctx, &s).Command) @@ -1258,28 +1298,28 @@ func NewTemporalServerStartDevCommand(cctx *CommandContext, parent *TemporalServ s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "start-dev [flags]" - s.Command.Short = "Start Temporal development server." + s.Command.Short = "Start Temporal development server" if hasHighlighting { - s.Command.Long = "Start Temporal Server on \x1b[1mlocalhost:7233\x1b[0m with:\n\n\x1b[1mtemporal server start-dev\x1b[0m\n\nView the UI at http://localhost:8233\n\nTo persist Workflows across runs, use:\n\n\x1b[1mtemporal server start-dev --db-filename temporal.db\x1b[0m" + s.Command.Long = "Run a development Temporal Server on your local system. View the Web UI for\nthe default configuration at http://localhost:8233:\n\n\x1b[1mtemporal server start-dev\x1b[0m\n\nAdd persistence for Workflow Executions across runs:\n\n\x1b[1mtemporal server start-dev \\\n --db-filename path-to-your-local-persistent-store\x1b[0m\n\nSet the port from the front-end gRPC Service (7233 default):\n\n\x1b[1mtemporal server start-dev \\\n --port 7000\x1b[0m\n\nUse a custom port for the Web UI. The default is the gRPC port (7233 default)\nplus 1000 (8233):\n\n\x1b[1mtemporal server start-dev \\\n --ui-port 3000\x1b[0m" } else { - s.Command.Long = "Start Temporal Server on `localhost:7233` with:\n\n`temporal server start-dev`\n\nView the UI at http://localhost:8233\n\nTo persist Workflows across runs, use:\n\n`temporal server start-dev --db-filename temporal.db`" + s.Command.Long = "Run a development Temporal Server on your local system. View the Web UI for\nthe default configuration at http://localhost:8233:\n\n```\ntemporal server start-dev\n```\n\nAdd persistence for Workflow Executions across runs:\n\n```\ntemporal server start-dev \\\n --db-filename path-to-your-local-persistent-store\n```\n\nSet the port from the front-end gRPC Service (7233 default):\n\n```\ntemporal server start-dev \\\n --port 7000\n```\n\nUse a custom port for the Web UI. The default is the gRPC port (7233 default)\nplus 1000 (8233):\n\n```\ntemporal server start-dev \\\n --ui-port 3000\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.DbFilename, "db-filename", "f", "", "File in which to persist Temporal state (by default, Workflows are lost when the process dies).") - s.Command.Flags().StringArrayVarP(&s.Namespace, "namespace", "n", nil, "Specify namespaces that should be pre-created (namespace \"default\" is always created).") - s.Command.Flags().IntVarP(&s.Port, "port", "p", 7233, "Port for the frontend gRPC service.") - s.Command.Flags().IntVar(&s.HttpPort, "http-port", 0, "Port for the frontend HTTP API service. Default is off.") - s.Command.Flags().IntVar(&s.MetricsPort, "metrics-port", 0, "Port for /metrics. Default is off.") - s.Command.Flags().IntVar(&s.UiPort, "ui-port", 0, "Port for the Web UI. Default is --port + 1000.") + s.Command.Flags().StringVarP(&s.DbFilename, "db-filename", "f", "", "Path to file for persistent Temporal state store. By default, Workflow Executions are lost when the server process dies.") + s.Command.Flags().StringArrayVarP(&s.Namespace, "namespace", "n", nil, "Namespaces to be created at launch. The \"default\" Namespace is always created automatically.") + s.Command.Flags().IntVarP(&s.Port, "port", "p", 7233, "Port for the frontend gRPC Service.") + s.Command.Flags().IntVar(&s.HttpPort, "http-port", 0, "Port for the HTTP API service. Default is off.") + s.Command.Flags().IntVar(&s.MetricsPort, "metrics-port", 0, "Port for '/metrics'. Default is off.") + s.Command.Flags().IntVar(&s.UiPort, "ui-port", 0, "Port for the Web UI. Default is '--port' value + 1000.") s.Command.Flags().BoolVar(&s.Headless, "headless", false, "Disable the Web UI.") - s.Command.Flags().StringVar(&s.Ip, "ip", "localhost", "IP address to bind the frontend service to.") - s.Command.Flags().StringVar(&s.UiIp, "ui-ip", "", "IP address to bind the Web UI to. Default is same as --ip.") + s.Command.Flags().StringVar(&s.Ip, "ip", "localhost", "IP address bound to the frontend Service.") + s.Command.Flags().StringVar(&s.UiIp, "ui-ip", "", "IP address bound to the WebUI. Default is same as '--ip' value.") s.Command.Flags().StringVar(&s.UiAssetPath, "ui-asset-path", "", "UI custom assets path.") s.Command.Flags().StringVar(&s.UiCodecEndpoint, "ui-codec-endpoint", "", "UI remote codec HTTP endpoint.") - s.Command.Flags().StringArrayVar(&s.SqlitePragma, "sqlite-pragma", nil, "Specify SQLite pragma statements in pragma=value format.") - s.Command.Flags().StringArrayVar(&s.DynamicConfigValue, "dynamic-config-value", nil, "Dynamic config value, as KEY=JSON_VALUE (string values need quotes).") - s.Command.Flags().BoolVar(&s.LogConfig, "log-config", false, "Log the server config being used to stderr.") - s.Command.Flags().StringArrayVar(&s.SearchAttribute, "search-attribute", nil, "Search attributes to register, in key=type format.") + s.Command.Flags().StringArrayVar(&s.SqlitePragma, "sqlite-pragma", nil, "SQLite pragma statements in \"PRAGMA=VALUE\" format.") + s.Command.Flags().StringArrayVar(&s.DynamicConfigValue, "dynamic-config-value", nil, "Dynamic configuration value using `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: 'YourKey=\"YourString\"'. Can be passed multiple times.") + s.Command.Flags().BoolVar(&s.LogConfig, "log-config", false, "Log the server config to stderr.") + s.Command.Flags().StringArrayVar(&s.SearchAttribute, "search-attribute", nil, "Search attributes to register using `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: 'YourKey={\"your\": \"value\"}'. Can be passed multiple times.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1298,11 +1338,11 @@ func NewTemporalTaskQueueCommand(cctx *CommandContext, parent *TemporalCommand) var s TemporalTaskQueueCommand s.Parent = parent s.Command.Use = "task-queue" - s.Command.Short = "Manage Task Queues." + s.Command.Short = "Manage Task Queues" if hasHighlighting { - s.Command.Long = "Task Queue commands allow operations to be performed on Task Queues. To run a Task\nQueue command, run \x1b[1mtemporal task-queue [command] [command options]\x1b[0m." + s.Command.Long = "Inspect and update Task Queues, the queues that Workers poll for Workflow and\nActivity tasks:\n\n\x1b[1mtemporal task-queue [command] [command options] \\\n --task-queue YourTaskQueue\x1b[0m\n\nFor example:\n\n\x1b[1mtemporal task-queue describe \\\n --task-queue YourTaskQueue\x1b[0m" } else { - s.Command.Long = "Task Queue commands allow operations to be performed on Task Queues. To run a Task\nQueue command, run `temporal task-queue [command] [command options]`." + s.Command.Long = "Inspect and update Task Queues, the queues that Workers poll for Workflow and\nActivity tasks:\n\n```\ntemporal task-queue [command] [command options] \\\n --task-queue YourTaskQueue\n```\n\nFor example:\n\n```\ntemporal task-queue describe \\\n --task-queue YourTaskQueue\n```" } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalTaskQueueDescribeCommand(cctx, &s).Command) @@ -1334,24 +1374,24 @@ func NewTemporalTaskQueueDescribeCommand(cctx *CommandContext, parent *TemporalT s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "describe [flags]" - s.Command.Short = "Provides task reachability and pollers information for Workers on this Task Queue." + s.Command.Short = "Show active Workers" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal task-queue describe\x1b[0m command provides task reachability information for the requested versions and all task types,\nwhich can be used to safely retire Workers with old code versions, provided that they were assigned a Build ID.\n\nThe reachability states of a Build ID are:\n - \x1b[1mReachable\x1b[0m: the Build ID may be used by new workflows or activities\n(based on versioning rules), or there are open workflows or backlogged activities assigned to it.\n - \x1b[1mClosedWorkflowsOnly\x1b[0m: the Build ID does not have open workflows, and is not reachable by new workflows, but MAY have closed workflows within the namespace retention period.\n - \x1b[1mUnreachable\x1b[0m: indicates that this Build ID is not used for new executions, nor has been used by any existing execution within the retention period.\n\nTask reachability is eventually consistent; there may be a delay until it converges to the most\naccurate value but it is designed in a way to take the more conservative side until it converges.\nFor example, \x1b[1mReachable\x1b[0m is more conservative than \x1b[1mClosedWorkflowsOnly\x1b[0m.\n\nThere is a non-trivial cost of computing task reachability, use the flag \x1b[1m--report-reachability\x1b[0m to enable it.\n\nThis command also provides poller\ninformation for a given Task Queue.\n\nThe Server records the last time of each poll request. A \x1b[1mLastAccessTime\x1b[0m value\nin excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the\nWorker has shut down. Workers are removed if 5 minutes have passed since the last poll\nrequest.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\nUse the options listed below to modify what this command returns.\n\nNote that without a \x1b[1m--select-*\x1b[0m option the result for the default Build ID will be returned.\nThe default Build ID is the one mentioned in the first unconditional Assignment Rule.\nIf there is no default Build ID, the result for the unversioned queue will be returned." + s.Command.Long = "Display a list of active Workers that have recently polled a Task Queue. The\nTemporal Server records each poll request time. A \x1b[1mLastAccessTime\x1b[0m over one\nminute may indicate the Worker is at capacity or has shut down. Temporal\nWorkers are removed if 5 minutes have passed since the last poll request.\n\n\x1b[1mtemporal task-queue describe \\\n --task-queue YourTaskQueue\x1b[0m\n\nThis command provides poller information for a given Task Queue.\nWorkflow and Activity polling use separate Task Queues:\n\n\x1b[1mtemporal task-queue describe \\\n --task-queue YourTaskQueue \\\n --task-queue-type \"activity\"\x1b[1m\x1b[0m\n\nSafely retire Workers assigned a Build ID by checking reachability across\nall task types. Use the flag \x1b[0m--report-reachability\x1b[1m:\n\n\x1b[1mtemporal task-queue describe \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\" \\\n --report-reachability\x1b[0m\n\nComputing task reachability incurs a non-trivial computing cost.\n\nBuild ID reachability states include:\n\n- \x1b[0mReachable\x1b[1m: using the current versioning rules, the Build ID may be used\n by new Workflow Executions or Activities OR there are currently open\n Workflow or backlogged Activity tasks assigned to the queue.\n- \x1b[0mClosedWorkflowsOnly\x1b[1m: the Build ID does not have open Workflow Executions\n and can't be reached by new Workflow Executions. It MAY have closed\n Workflow Executions within the Namespace retention period.\n- \x1b[0mUnreachable\x1b[1m: this Build ID is not used for new Workflow Executions and\n isn't used by any existing Workflow Execution within the retention period.\n\nTask reachability is eventually consistent. You may experience a delay until\nreachability converges to the most accurate value. This is designed to act\nin the most conservative way until convergence. For example, \x1b[0mReachable\x1b[1m is\nmore conservative than \x1b[0mClosedWorkflowsOnly`." } else { - s.Command.Long = "The `temporal task-queue describe` command provides task reachability information for the requested versions and all task types,\nwhich can be used to safely retire Workers with old code versions, provided that they were assigned a Build ID.\n\nThe reachability states of a Build ID are:\n - `Reachable`: the Build ID may be used by new workflows or activities\n(based on versioning rules), or there are open workflows or backlogged activities assigned to it.\n - `ClosedWorkflowsOnly`: the Build ID does not have open workflows, and is not reachable by new workflows, but MAY have closed workflows within the namespace retention period.\n - `Unreachable`: indicates that this Build ID is not used for new executions, nor has been used by any existing execution within the retention period.\n\nTask reachability is eventually consistent; there may be a delay until it converges to the most\naccurate value but it is designed in a way to take the more conservative side until it converges.\nFor example, `Reachable` is more conservative than `ClosedWorkflowsOnly`.\n\nThere is a non-trivial cost of computing task reachability, use the flag `--report-reachability` to enable it.\n\nThis command also provides poller\ninformation for a given Task Queue.\n\nThe Server records the last time of each poll request. A `LastAccessTime` value\nin excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the\nWorker has shut down. Workers are removed if 5 minutes have passed since the last poll\nrequest.\n\nInformation about the Task Queue can be returned to troubleshoot server issues.\n\nUse the options listed below to modify what this command returns.\n\nNote that without a `--select-*` option the result for the default Build ID will be returned.\nThe default Build ID is the one mentioned in the first unconditional Assignment Rule.\nIf there is no default Build ID, the result for the unversioned queue will be returned." + s.Command.Long = "Display a list of active Workers that have recently polled a Task Queue. The\nTemporal Server records each poll request time. A `LastAccessTime` over one\nminute may indicate the Worker is at capacity or has shut down. Temporal\nWorkers are removed if 5 minutes have passed since the last poll request.\n\n```\ntemporal task-queue describe \\\n --task-queue YourTaskQueue\n```\n\nThis command provides poller information for a given Task Queue.\nWorkflow and Activity polling use separate Task Queues:\n\n```\ntemporal task-queue describe \\\n --task-queue YourTaskQueue \\\n --task-queue-type \"activity\"`\n```\n\nSafely retire Workers assigned a Build ID by checking reachability across\nall task types. Use the flag `--report-reachability`:\n\n```\ntemporal task-queue describe \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\" \\\n --report-reachability\n```\n\nComputing task reachability incurs a non-trivial computing cost.\n\nBuild ID reachability states include:\n\n- `Reachable`: using the current versioning rules, the Build ID may be used\n by new Workflow Executions or Activities OR there are currently open\n Workflow or backlogged Activity tasks assigned to the queue.\n- `ClosedWorkflowsOnly`: the Build ID does not have open Workflow Executions\n and can't be reached by new Workflow Executions. It MAY have closed\n Workflow Executions within the Namespace retention period.\n- `Unreachable`: this Build ID is not used for new Workflow Executions and\n isn't used by any existing Workflow Execution within the retention period.\n\nTask reachability is eventually consistent. You may experience a delay until\nreachability converges to the most accurate value. This is designed to act\nin the most conservative way until convergence. For example, `Reachable` is\nmore conservative than `ClosedWorkflowsOnly`." } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task queue name. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "task-queue") - s.Command.Flags().StringArrayVar(&s.TaskQueueType, "task-queue-type", nil, "Task queue types considered. If not specified, all types are reported. The current valid queue types are workflow, activity, or nexus.") - s.Command.Flags().StringArrayVar(&s.SelectBuildId, "select-build-id", nil, "Task queue filter based on Build ID.") + s.Command.Flags().StringArrayVar(&s.TaskQueueType, "task-queue-type", nil, "Task Queue type. Options are: workflow, activity, nexus.") + s.Command.Flags().StringArrayVar(&s.SelectBuildId, "select-build-id", nil, "Filter the Task Queue based on Build ID.") s.Command.Flags().BoolVar(&s.SelectUnversioned, "select-unversioned", false, "Include the unversioned queue.") s.Command.Flags().BoolVar(&s.SelectAllActive, "select-all-active", false, "Include all active versions. A version is active if it had new tasks or polls recently.") s.Command.Flags().BoolVar(&s.ReportReachability, "report-reachability", false, "Display task reachability information.") s.Command.Flags().BoolVar(&s.LegacyMode, "legacy-mode", false, "Enable a legacy mode for servers that do not support rules-based worker versioning. This mode only provides pollers info.") s.TaskQueueTypeLegacy = NewStringEnum([]string{"workflow", "activity"}, "workflow") s.Command.Flags().Var(&s.TaskQueueTypeLegacy, "task-queue-type-legacy", "Task Queue type (legacy mode only). Accepted values: workflow, activity.") - s.Command.Flags().IntVar(&s.PartitionsLegacy, "partitions-legacy", 1, "Query for all partitions up to this number (experimental+temporary feature) (legacy mode only).") + s.Command.Flags().IntVar(&s.PartitionsLegacy, "partitions-legacy", 1, "Query partitions 1 through `N`. Experimental/Temporary feature. Legacy mode only.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1373,13 +1413,17 @@ func NewTemporalTaskQueueGetBuildIdReachabilityCommand(cctx *CommandContext, par s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "get-build-id-reachability [flags]" - s.Command.Short = "Retrieves information about the reachability of Build IDs on one or more Task Queues (Deprecated)." - s.Command.Long = "This command can tell you whether or not Build IDs may be used for new, existing, or closed workflows. Both the '--build-id' and '--task-queue' flags may be specified multiple times. If you do not provide a task queue, reachability for the provided Build IDs will be checked against all task queues." + s.Command.Short = "Show Build ID availability (Deprecated)" + if hasHighlighting { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nShow if a given Build ID can be used for new, existing, or closed Workflows\nin Namespaces that support Worker versioning:\n\n\x1b[1mtemporal task-queue get-build-id-reachability \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\"\x1b[0m\n\nYou can specify the \x1b[1m--build-id\x1b[0m and \x1b[1m--task-queue\x1b[0m flags multiple times. If\n\x1b[1m--task-queue\x1b[0m is omitted, the command checks Build ID reachability against\nall Task Queues." + } else { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nShow if a given Build ID can be used for new, existing, or closed Workflows\nin Namespaces that support Worker versioning:\n\n```\ntemporal task-queue get-build-id-reachability \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\"\n```\n\nYou can specify the `--build-id` and `--task-queue` flags multiple times. If\n`--task-queue` is omitted, the command checks Build ID reachability against\nall Task Queues." + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringArrayVar(&s.BuildId, "build-id", nil, "Which Build ID to get reachability information for. May be specified multiple times.") + s.Command.Flags().StringArrayVar(&s.BuildId, "build-id", nil, "One or more Build ID strings. Can be passed multiple times.") s.ReachabilityType = NewStringEnum([]string{"open", "closed", "existing"}, "existing") - s.Command.Flags().Var(&s.ReachabilityType, "reachability-type", "Specify how you'd like to filter the reachability of Build IDs. Valid choices are `open` (reachable by one or more open workflows), `closed` (reachable by one or more closed workflows), or `existing` (reachable by either). If a Build ID is reachable by new workflows, that is always reported. Accepted values: open, closed, existing.") - s.Command.Flags().StringArrayVarP(&s.TaskQueue, "task-queue", "t", nil, "Which Task Queue(s) to constrain the reachability search to. May be specified multiple times.") + s.Command.Flags().Var(&s.ReachabilityType, "reachability-type", "Reachability filter. `open`: reachable by one or more open workflows. `closed`: reachable by one or more closed workflows. `existing`: reachable by either. New Workflow Executions reachable by a Build ID are always reported. Accepted values: open, closed, existing.") + s.Command.Flags().StringArrayVarP(&s.TaskQueue, "task-queue", "t", nil, "Search only the specified task queue(s). Can be passed multiple times.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1400,12 +1444,16 @@ func NewTemporalTaskQueueGetBuildIdsCommand(cctx *CommandContext, parent *Tempor s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "get-build-ids [flags]" - s.Command.Short = "Fetch the sets of worker Build ID versions on the Task Queue (Deprecated)." - s.Command.Long = "Fetch the sets of compatible build IDs associated with a Task Queue and associated information." + s.Command.Short = "Fetch Build ID versions (Deprecated)" + if hasHighlighting { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nFetch sets of compatible Build IDs for specified Task Queues and display their\ninformation:\n\n\x1b[1mtemporal task-queue get-build-ids \\\n --task-queue YourTaskQueue\x1b[0m\n\nThis command is limited to Namespaces that support Worker versioning." + } else { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nFetch sets of compatible Build IDs for specified Task Queues and display their\ninformation:\n\n```\ntemporal task-queue get-build-ids \\\n --task-queue YourTaskQueue\n```\n\nThis command is limited to Namespaces that support Worker versioning." + } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task queue name. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "task-queue") - s.Command.Flags().IntVar(&s.MaxSets, "max-sets", 0, "Limits how many compatible sets will be returned. Specify 1 to only return the current default major version set. 0 returns all sets. (default: 0).") + s.Command.Flags().IntVar(&s.MaxSets, "max-sets", 0, "Max return count. Use 1 for default major version. Use 0 for all sets.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1425,10 +1473,14 @@ func NewTemporalTaskQueueListPartitionCommand(cctx *CommandContext, parent *Temp s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "list-partition [flags]" - s.Command.Short = "Lists the Task Queue's partitions and the matching nodes they are assigned to." - s.Command.Long = "The temporal task-queue list-partition command displays the partitions of a Task Queue, along with the matching node they are assigned to." + s.Command.Short = "List Task Queue partitions" + if hasHighlighting { + s.Command.Long = "Display a Task Queue's partition list with assigned matching nodes:\n\n\x1b[1mtemporal task-queue list-partition \\\n --task-queue YourTaskQueue\x1b[0m" + } else { + s.Command.Long = "Display a Task Queue's partition list with assigned matching nodes:\n\n```\ntemporal task-queue list-partition \\\n --task-queue YourTaskQueue\n```" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task queue name. Required.") + s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task Queue name. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "task-queue") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -1447,8 +1499,12 @@ func NewTemporalTaskQueueUpdateBuildIdsCommand(cctx *CommandContext, parent *Tem var s TemporalTaskQueueUpdateBuildIdsCommand s.Parent = parent s.Command.Use = "update-build-ids" - s.Command.Short = "Operations to update the sets of worker Build ID versions on the Task Queue (Deprecated)." - s.Command.Long = "Provides various commands for adding or changing the sets of compatible build IDs associated with a Task Queue. See the help of each sub-command for more." + s.Command.Short = "Manage Build IDs (Deprecated)" + if hasHighlighting { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nAdd or change a Task Queue's compatible Build IDs for Namespaces using Worker\nversioning:\n\n\x1b[1mtemporal task-queue update-build-ids [subcommands] [options] \\\n --task-queue YourTaskQueue\x1b[0m" + } else { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nAdd or change a Task Queue's compatible Build IDs for Namespaces using Worker\nversioning:\n\n```\ntemporal task-queue update-build-ids [subcommands] [options] \\\n --task-queue YourTaskQueue\n```" + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalTaskQueueUpdateBuildIdsAddNewCompatibleCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalTaskQueueUpdateBuildIdsAddNewDefaultCommand(cctx, &s).Command) @@ -1471,16 +1527,20 @@ func NewTemporalTaskQueueUpdateBuildIdsAddNewCompatibleCommand(cctx *CommandCont s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "add-new-compatible [flags]" - s.Command.Short = "Add a new build ID compatible with an existing ID to the Task Queue version sets." - s.Command.Long = "The new build ID will become the default for the set containing the existing ID. See per-flag help for more." + s.Command.Short = "Add compatible Build ID" + if hasHighlighting { + s.Command.Long = "Add a compatible Build ID to a Task Queue's existing version set. Provide an\nexisting Build ID and a new Build ID:\n\n\x1b[1mtemporal task-queue update-build-ids add-new-compatible \\\n --task-queue YourTaskQueue \\\n --existing-compatible-build-id \"YourExistingBuildId\" \\\n --build-id \"YourNewBuildId\"\x1b[0m\n\nThe new ID is stored in the set containing the existing ID and becomes the new\ndefault for that set.\n\nThis command is limited to Namespaces that support Worker versioning." + } else { + s.Command.Long = "Add a compatible Build ID to a Task Queue's existing version set. Provide an\nexisting Build ID and a new Build ID:\n\n```\ntemporal task-queue update-build-ids add-new-compatible \\\n --task-queue YourTaskQueue \\\n --existing-compatible-build-id \"YourExistingBuildId\" \\\n --build-id \"YourNewBuildId\"\n```\n\nThe new ID is stored in the set containing the existing ID and becomes the new\ndefault for that set.\n\nThis command is limited to Namespaces that support Worker versioning." + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "The new build id to be added. Required.") + s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Build ID to be added. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id") - s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Name of the Task Queue. Required.") + s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task Queue name. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "task-queue") - s.Command.Flags().StringVar(&s.ExistingCompatibleBuildId, "existing-compatible-build-id", "", "A build id which must already exist in the version sets known by the task queue. The new id will be stored in the set containing this id, marking it as compatible with the versions within. Required.") + s.Command.Flags().StringVar(&s.ExistingCompatibleBuildId, "existing-compatible-build-id", "", "Pre-existing Build ID in this Task Queue. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "existing-compatible-build-id") - s.Command.Flags().BoolVar(&s.SetAsDefault, "set-as-default", false, "When set, establishes the compatible set being targeted as the overall default for the queue. If a different set was the current default, the targeted set will replace it as the new default. Defaults to false.") + s.Command.Flags().BoolVar(&s.SetAsDefault, "set-as-default", false, "Set the expanded Build ID set as the Task Queue default. Defaults to false.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1501,12 +1561,16 @@ func NewTemporalTaskQueueUpdateBuildIdsAddNewDefaultCommand(cctx *CommandContext s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "add-new-default [flags]" - s.Command.Short = "Add a new default (incompatible) build ID to the Task Queue version sets." - s.Command.Long = "Creates a new build id set which will become the new overall default for the queue with the provided build id as its only member. This new set is incompatible with all previous sets/versions." + s.Command.Short = "Set new default Build ID set (Deprecated)" + if hasHighlighting { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nCreate a new Task Queue Build ID set, add a Build ID to it, and make it the\noverall Task Queue default. The new set will be incompatible with previous\nsets and versions.\n\n\x1b[1mtemporal task-queue update-build-ids add-new-default \\\n --task-queue YourTaskQueue \\\n --build-id \"YourNewBuildId\"\x1b[0m\n\n+------------------------------------------------------------------------+\n| NOTICE: This command is limited to Namespaces that support Worker |\n| versioning. Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+------------------------------------------------------------------------+" + } else { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nCreate a new Task Queue Build ID set, add a Build ID to it, and make it the\noverall Task Queue default. The new set will be incompatible with previous\nsets and versions.\n\n```\ntemporal task-queue update-build-ids add-new-default \\\n --task-queue YourTaskQueue \\\n --build-id \"YourNewBuildId\"\n```\n\n+------------------------------------------------------------------------+\n| NOTICE: This command is limited to Namespaces that support Worker |\n| versioning. Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+------------------------------------------------------------------------+" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "The new build id to be added. Required.") + s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Build ID to be added. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id") - s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Name of the Task Queue. Required.") + s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task Queue name. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "task-queue") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -1528,12 +1592,16 @@ func NewTemporalTaskQueueUpdateBuildIdsPromoteIdInSetCommand(cctx *CommandContex s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "promote-id-in-set [flags]" - s.Command.Short = "Promote an existing build ID to become the default for its containing set." - s.Command.Long = "New tasks compatible with the set will be dispatched to the default id." + s.Command.Short = "Set Build ID as set default (Deprecated)" + if hasHighlighting { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nEstablish an existing Build ID as the default in its Task Queue set. New tasks\ncompatible with this set will now be dispatched to this ID:\n\n\x1b[1mtemporal task-queue update-build-ids promote-id-in-set \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\"\x1b[0m\n\n+------------------------------------------------------------------------+\n| NOTICE: This command is limited to Namespaces that support Worker |\n| versioning. Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+------------------------------------------------------------------------+" + } else { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nEstablish an existing Build ID as the default in its Task Queue set. New tasks\ncompatible with this set will now be dispatched to this ID:\n\n```\ntemporal task-queue update-build-ids promote-id-in-set \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\"\n```\n\n+------------------------------------------------------------------------+\n| NOTICE: This command is limited to Namespaces that support Worker |\n| versioning. Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+------------------------------------------------------------------------+" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "An existing build id which will be promoted to be the default inside its containing set. Required.") + s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Build ID to set as default. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id") - s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Name of the Task Queue. Required.") + s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task Queue name. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "task-queue") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -1555,12 +1623,16 @@ func NewTemporalTaskQueueUpdateBuildIdsPromoteSetCommand(cctx *CommandContext, p s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "promote-set [flags]" - s.Command.Short = "Promote an existing build ID set to become the default for the Task Queue." - s.Command.Long = "If the set is already the default, this command has no effect." + s.Command.Short = "Promote Build ID set (Deprecated)" + if hasHighlighting { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nPromote a Build ID set to be the default on a Task Queue. Identify the set by\nproviding a Build ID within it. If the set is already the default, this\ncommand has no effect:\n\n\x1b[1mtemporal task-queue update-build-ids promote-set \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\"\x1b[0m\n\n+------------------------------------------------------------------------+\n| NOTICE: This command is limited to Namespaces that support Worker |\n| versioning. Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+------------------------------------------------------------------------+" + } else { + s.Command.Long = "+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n\nPromote a Build ID set to be the default on a Task Queue. Identify the set by\nproviding a Build ID within it. If the set is already the default, this\ncommand has no effect:\n\n```\ntemporal task-queue update-build-ids promote-set \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\"\n```\n\n+------------------------------------------------------------------------+\n| NOTICE: This command is limited to Namespaces that support Worker |\n| versioning. Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+------------------------------------------------------------------------+" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "An existing build id whose containing set will be promoted. Required.") + s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Build ID within the promoted set. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id") - s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Name of the Task Queue. Required.") + s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task Queue name. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "task-queue") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -1580,8 +1652,12 @@ func NewTemporalTaskQueueVersioningCommand(cctx *CommandContext, parent *Tempora var s TemporalTaskQueueVersioningCommand s.Parent = parent s.Command.Use = "versioning" - s.Command.Short = "Updates or retrieves the worker Build ID assignment and redirect rules on the Task Queue." - s.Command.Long = "Provides various commands for adding, listing, removing, or replacing worker Build ID assignment and redirect rules associated with a Task Queue. See the help of each sub-command for more." + s.Command.Short = "manage Task Queue Build ID handling (Experimental)" + if hasHighlighting { + s.Command.Long = "+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n\x1b[1mtemporal task-queue versioning [subcommands] [options] \\\n --task-queue YourTaskQueue\x1b[0m\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n which are evaluated from first to last. Assignment Rules also allow for\n gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n Build ID. You may add at most one redirect rule for each source Build ID.\n Redirect rules require that a target Build ID is fully compatible with\n the source Build ID." + } else { + s.Command.Long = "+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n```\ntemporal task-queue versioning [subcommands] [options] \\\n --task-queue YourTaskQueue\n```\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n which are evaluated from first to last. Assignment Rules also allow for\n gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n Build ID. You may add at most one redirect rule for each source Build ID.\n Redirect rules require that a target Build ID is fully compatible with\n the source Build ID." + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalTaskQueueVersioningAddRedirectRuleCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalTaskQueueVersioningCommitBuildIdCommand(cctx, &s).Command) @@ -1609,14 +1685,18 @@ func NewTemporalTaskQueueVersioningAddRedirectRuleCommand(cctx *CommandContext, s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "add-redirect-rule [flags]" - s.Command.Short = "Adds the rule to the list of redirect rules for this Task Queue." - s.Command.Long = "Adds a new redirect rule for this Task Queue. There can be at most one redirect rule for each distinct source build ID." + s.Command.Short = "Add Task Queue redirect rules (Experimental)" + if hasHighlighting { + s.Command.Long = "Add a new redirect rule for a given Task Queue. You may add at most one\nredirect rule for each distinct source build ID:\n\n\x1b[1mtemporal task-queue versioning add-redirect-rule \\\n --task-queue YourTaskQueue \\\n --source-build-id \"YourSourceBuildID\" \\\n --target-build-id \"YourTargetBuildID\"\x1b[0m\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } else { + s.Command.Long = "Add a new redirect rule for a given Task Queue. You may add at most one\nredirect rule for each distinct source build ID:\n\n```\ntemporal task-queue versioning add-redirect-rule \\\n --task-queue YourTaskQueue \\\n --source-build-id \"YourSourceBuildID\" \\\n --target-build-id \"YourTargetBuildID\"\n```\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.SourceBuildId, "source-build-id", "", "The source build ID for this redirect rule. Required.") + s.Command.Flags().StringVar(&s.SourceBuildId, "source-build-id", "", "Source build ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "source-build-id") - s.Command.Flags().StringVar(&s.TargetBuildId, "target-build-id", "", "The target build ID for this redirect rule. Required.") + s.Command.Flags().StringVar(&s.TargetBuildId, "target-build-id", "", "Target build ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "target-build-id") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Skip confirmation.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1638,17 +1718,17 @@ func NewTemporalTaskQueueVersioningCommitBuildIdCommand(cctx *CommandContext, pa s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "commit-build-id [flags]" - s.Command.Short = "Completes the rollout of a Build ID for this Task Queue." + s.Command.Short = "Complete Build ID rollout (Experimental)" if hasHighlighting { - s.Command.Long = "Completes the rollout of a BuildID and cleanup unnecessary rules possibly\ncreated during a gradual rollout. Specifically, this command will make the\nfollowing changes atomically:\n\t1. Adds an unconditional assignment rule for the target Build ID at the end of the list.\n\t2. Removes all previously added assignment rules to the given target Build ID.\n\t3. Removes any unconditional assignment rules for other Build IDs.\n\nTo prevent committing invalid Build IDs, we reject the request if no pollers\nhave been seen recently for this Build ID. Use the \x1b[1mforce\x1b[0m option to disable this validation." + s.Command.Long = "Complete a Build ID's rollout and clean up unnecessary rules that might have\nbeen created during a gradual rollout:\n\n\x1b[1mtemporal task-queue versioning commit-build-id \\\n --task-queue YourTaskQueue\n --build-id \"YourBuildId\"\x1b[0m\n\nThis command automatically applies the following atomic changes:\n\n- Adds an unconditional assignment rule for the target Build ID at the\n end of the list.\n- Removes all previously added assignment rules to the given target\n Build ID.\n- Removes any unconditional assignment rules for other Build IDs.\n\nRejects requests when there have been no recent pollers for this Build ID.\nThis prevents committing invalid Build IDs. Use the \x1b[1m--force\x1b[0m option to\noverride this validation.\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" } else { - s.Command.Long = "Completes the rollout of a BuildID and cleanup unnecessary rules possibly\ncreated during a gradual rollout. Specifically, this command will make the\nfollowing changes atomically:\n\t1. Adds an unconditional assignment rule for the target Build ID at the end of the list.\n\t2. Removes all previously added assignment rules to the given target Build ID.\n\t3. Removes any unconditional assignment rules for other Build IDs.\n\nTo prevent committing invalid Build IDs, we reject the request if no pollers\nhave been seen recently for this Build ID. Use the `force` option to disable this validation." + s.Command.Long = "Complete a Build ID's rollout and clean up unnecessary rules that might have\nbeen created during a gradual rollout:\n\n```\ntemporal task-queue versioning commit-build-id \\\n --task-queue YourTaskQueue\n --build-id \"YourBuildId\"\n```\n\nThis command automatically applies the following atomic changes:\n\n- Adds an unconditional assignment rule for the target Build ID at the\n end of the list.\n- Removes all previously added assignment rules to the given target\n Build ID.\n- Removes any unconditional assignment rules for other Build IDs.\n\nRejects requests when there have been no recent pollers for this Build ID.\nThis prevents committing invalid Build IDs. Use the `--force` option to\noverride this validation.\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "The target build ID to be committed. Required.") + s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Target build ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id") - s.Command.Flags().BoolVar(&s.Force, "force", false, "Bypass the validation that pollers have been recently seen for this build ID.") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Skip confirmation.") + s.Command.Flags().BoolVar(&s.Force, "force", false, "Bypass recent-poller validation.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1661,8 +1741,8 @@ type TemporalTaskQueueVersioningDeleteAssignmentRuleCommand struct { Parent *TemporalTaskQueueVersioningCommand Command cobra.Command RuleIndex int - Yes bool Force bool + Yes bool } func NewTemporalTaskQueueVersioningDeleteAssignmentRuleCommand(cctx *CommandContext, parent *TemporalTaskQueueVersioningCommand) *TemporalTaskQueueVersioningDeleteAssignmentRuleCommand { @@ -1670,17 +1750,17 @@ func NewTemporalTaskQueueVersioningDeleteAssignmentRuleCommand(cctx *CommandCont s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "delete-assignment-rule [flags]" - s.Command.Short = "Deletes the rule at a given index in the list of assignment rules for this Task Queue." + s.Command.Short = "Removes a Task Queue assignment rule (Experimental)" if hasHighlighting { - s.Command.Long = "Deletes an assignment rule for this Task Queue. By default presence of one\nunconditional rule, i.e., no hint filter or percentage, is enforced, otherwise\nthe delete operation will be rejected. Set \x1b[1mforce\x1b[0m to true to bypass this\nvalidation." + s.Command.Long = "Deletes a rule identified by its index in the Task Queue's list of assignment\nrules.\n\n\x1b[1mtemporal task-queue versioning delete-assignment-rule \\\n --task-queue YourTaskQueue \\\n --rule-index YourIntegerRuleIndex\x1b[0m\n\nBy default, the Task Queue must retain one unconditional rule, such as \"no\nhint filter\" or \"percentage\". Otherwise, the delete operation is rejected.\nUse the \x1b[1m--force\x1b[0m option to override this validation.\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" } else { - s.Command.Long = "Deletes an assignment rule for this Task Queue. By default presence of one\nunconditional rule, i.e., no hint filter or percentage, is enforced, otherwise\nthe delete operation will be rejected. Set `force` to true to bypass this\nvalidation." + s.Command.Long = "Deletes a rule identified by its index in the Task Queue's list of assignment\nrules.\n\n```\ntemporal task-queue versioning delete-assignment-rule \\\n --task-queue YourTaskQueue \\\n --rule-index YourIntegerRuleIndex\n```\n\nBy default, the Task Queue must retain one unconditional rule, such as \"no\nhint filter\" or \"percentage\". Otherwise, the delete operation is rejected.\nUse the `--force` option to override this validation.\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" } s.Command.Args = cobra.NoArgs - s.Command.Flags().IntVarP(&s.RuleIndex, "rule-index", "i", 0, "Position of the assignment rule to be replaced. Required.") + s.Command.Flags().IntVarP(&s.RuleIndex, "rule-index", "i", 0, "Position of the assignment rule to be replaced. Requests for invalid indices will fail. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "rule-index") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Skip confirmation.") - s.Command.Flags().BoolVar(&s.Force, "force", false, "Bypass the validation that one unconditional rule remains.") + s.Command.Flags().BoolVar(&s.Force, "force", false, "Bypass one-unconditional-rule validation.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1701,12 +1781,16 @@ func NewTemporalTaskQueueVersioningDeleteRedirectRuleCommand(cctx *CommandContex s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "delete-redirect-rule [flags]" - s.Command.Short = "Deletes the rule with the given build ID for this Task Queue." - s.Command.Long = "Deletes the routing rule with the given source Build ID." + s.Command.Short = "Removes Build-ID routing rule (Experimental)" + if hasHighlighting { + s.Command.Long = "Deletes the routing rule for the given source Build ID.\n\n\x1b[1mtemporal task-queue versioning delete-redirect-rule \\\n --task-queue YourTaskQueue \\\n --source-build-id \"YourBuildId\"\x1b[0m\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } else { + s.Command.Long = "Deletes the routing rule for the given source Build ID.\n\n```\ntemporal task-queue versioning delete-redirect-rule \\\n --task-queue YourTaskQueue \\\n --source-build-id \"YourBuildId\"\n```\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.SourceBuildId, "source-build-id", "", "The source build ID for this redirect rule. Required.") + s.Command.Flags().StringVar(&s.SourceBuildId, "source-build-id", "", "Source Build ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "source-build-id") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Skip confirmation.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1725,8 +1809,12 @@ func NewTemporalTaskQueueVersioningGetRulesCommand(cctx *CommandContext, parent s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "get-rules [flags]" - s.Command.Short = "Retrieves the worker Build ID assignment and redirect rules on the Task Queue." - s.Command.Long = "Fetch the worker build ID assignment and redirect rules associated with a Task Queue." + s.Command.Short = "Fetch Worker Build ID assignments and redirect rules (Experimental)" + if hasHighlighting { + s.Command.Long = "Retrieve all the Worker Build ID assignments and redirect rules associated\nwith a Task Queue.\n\n\x1b[1mtemporal task-queue versioning get-rules \\\n --task-queue YourTaskQueue\x1b[0m\n\nTask Queues support the following versioning rules:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n which are evaluated from first to last. Assignment Rules also allow for\n gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n Build ID. You may add at most one redirect rule for each source Build ID.\n Redirect rules require that a target Build ID is fully compatible with\n the source Build ID.\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } else { + s.Command.Long = "Retrieve all the Worker Build ID assignments and redirect rules associated\nwith a Task Queue.\n\n```\ntemporal task-queue versioning get-rules \\\n --task-queue YourTaskQueue\n```\n\nTask Queues support the following versioning rules:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n which are evaluated from first to last. Assignment Rules also allow for\n gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n Build ID. You may add at most one redirect rule for each source Build ID.\n Redirect rules require that a target Build ID is fully compatible with\n the source Build ID.\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -1750,14 +1838,18 @@ func NewTemporalTaskQueueVersioningInsertAssignmentRuleCommand(cctx *CommandCont s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "insert-assignment-rule [flags]" - s.Command.Short = "Inserts the rule to the list of assignment rules for this Task Queue." - s.Command.Long = "Inserts a new assignment rule for this Task Queue. The rules are evaluated in order, starting from index 0. The first applicable rule will be applied and the rest will be ignored." + s.Command.Short = "Add an assignment rule at a index (Experimental)" + if hasHighlighting { + s.Command.Long = "Inserts a new assignment rule for this Task Queue. Rules are evaluated in\norder, starting from index 0. The first applicable rule is applied, and the\nrest ignored:\n\n\x1b[1mtemporal task-queue versioning insert-assignment-rule \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\"\x1b[0m\n\nIf you do not specify a \x1b[1m--rule-index\x1b[0m, this command inserts at index 0.\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } else { + s.Command.Long = "Inserts a new assignment rule for this Task Queue. Rules are evaluated in\norder, starting from index 0. The first applicable rule is applied, and the\nrest ignored:\n\n```\ntemporal task-queue versioning insert-assignment-rule \\\n --task-queue YourTaskQueue \\\n --build-id \"YourBuildId\"\n```\n\nIf you do not specify a `--rule-index`, this command inserts at index 0.\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "The target build ID for this assignment rule. Required.") + s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Target Build ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id") - s.Command.Flags().IntVarP(&s.RuleIndex, "rule-index", "i", 0, "Insertion position in the assignment rule list. An index 0 means insert at the beginning of the list. If the given index is larger than the list size, the rule will be appended at the end of the list.") - s.Command.Flags().IntVar(&s.Percentage, "percentage", 100, "Percentage of traffic sent to the target build ID.") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Skip confirmation.") + s.Command.Flags().IntVarP(&s.RuleIndex, "rule-index", "i", 0, "Insertion position. Ranges from 0 (insert at start) to count (append). Any number greater than the count is treated as \"append\".") + s.Command.Flags().IntVar(&s.Percentage, "percentage", 100, "Traffic percent to send to target Build ID.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1781,19 +1873,19 @@ func NewTemporalTaskQueueVersioningReplaceAssignmentRuleCommand(cctx *CommandCon s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "replace-assignment-rule [flags]" - s.Command.Short = "Replaces the rule at a given index in the list of assignment rules for this Task Queue." + s.Command.Short = "Update assignment rule at index (Experimental)" if hasHighlighting { - s.Command.Long = "Replaces an assignment rule for this Task Queue. By default presence of one\nunconditional rule, i.e., no hint filter or percentage, is enforced, otherwise\nthe delete operation will be rejected. Set \x1b[1mforce\x1b[0m to true to bypass this\nvalidation." + s.Command.Long = "Change an assignment rule for this Task Queue. By default, this enforces one\nunconditional rule (no hint filter or percentage). Otherwise, the operation\nwill be rejected. Set \x1b[1mforce\x1b[0m to true to bypass this validation.\n\n\x1b[1mtemporal task-queue versioning replace-assignment-rule\n --task-queue YourTaskQueue \\\n --rule-index AnIntegerIndex \\\n --build-id \"YourBuildId\"\x1b[0m\n\nTo assign multiple assignment rules to a single Build ID, use\n'insert-assignment-rule'.\n\nTo update the percent:\n\n\x1b[1mtemporal task-queue versioning replace-assignment-rule\n --task-queue YourTaskQueue \\\n --rule-index AnIntegerIndex \\\n --build-id \"YourBuildId\" \\\n --percentage AnIntegerPercent\x1b[0m\n\nPercent may vary between 0 and 100 (default).\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" } else { - s.Command.Long = "Replaces an assignment rule for this Task Queue. By default presence of one\nunconditional rule, i.e., no hint filter or percentage, is enforced, otherwise\nthe delete operation will be rejected. Set `force` to true to bypass this\nvalidation." + s.Command.Long = "Change an assignment rule for this Task Queue. By default, this enforces one\nunconditional rule (no hint filter or percentage). Otherwise, the operation\nwill be rejected. Set `force` to true to bypass this validation.\n\n```\ntemporal task-queue versioning replace-assignment-rule\n --task-queue YourTaskQueue \\\n --rule-index AnIntegerIndex \\\n --build-id \"YourBuildId\"\n```\n\nTo assign multiple assignment rules to a single Build ID, use\n'insert-assignment-rule'.\n\nTo update the percent:\n\n```\ntemporal task-queue versioning replace-assignment-rule\n --task-queue YourTaskQueue \\\n --rule-index AnIntegerIndex \\\n --build-id \"YourBuildId\" \\\n --percentage AnIntegerPercent\n```\n\nPercent may vary between 0 and 100 (default).\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "The target build ID for this assignment rule. Required.") + s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Target Build ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id") - s.Command.Flags().IntVarP(&s.RuleIndex, "rule-index", "i", 0, "Position of the assignment rule to be replaced. Required.") + s.Command.Flags().IntVarP(&s.RuleIndex, "rule-index", "i", 0, "Position of the assignment rule to be replaced. Requests for invalid indices will fail. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "rule-index") - s.Command.Flags().IntVar(&s.Percentage, "percentage", 100, "Percentage of traffic sent to the target build ID.") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Skip confirmation.") + s.Command.Flags().IntVar(&s.Percentage, "percentage", 100, "Divert percent of traffic to target Build ID.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm.") s.Command.Flags().BoolVar(&s.Force, "force", false, "Bypass the validation that one unconditional rule remains.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -1816,14 +1908,18 @@ func NewTemporalTaskQueueVersioningReplaceRedirectRuleCommand(cctx *CommandConte s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "replace-redirect-rule [flags]" - s.Command.Short = "Replaces the redirect rule with the given source build ID for this Task Queue." - s.Command.Long = "Replaces the redirect rule with the given source build ID for this Task Queue." + s.Command.Short = "Change the target for a Build ID's redirect (Experimental)" + if hasHighlighting { + s.Command.Long = "Updates a Build ID's redirect rule on a Task Queue by replacing its target\nBuild ID.\n\n\x1b[1mtemporal task-queue versioning replace-redirect-rule\n --task-queue YourTaskQueue \\\n --source-build-id YourSourceBuildId \\\n --target-build-id YourNewTargetBuildId\x1b[0m\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } else { + s.Command.Long = "Updates a Build ID's redirect rule on a Task Queue by replacing its target\nBuild ID.\n\n```\ntemporal task-queue versioning replace-redirect-rule\n --task-queue YourTaskQueue \\\n --source-build-id YourSourceBuildId \\\n --target-build-id YourNewTargetBuildId\n```\n\n+---------------------------------------------------------------------+\n| CAUTION: Worker versioning is experimental. Versioning commands are |\n| subject to change. |\n+---------------------------------------------------------------------+" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.SourceBuildId, "source-build-id", "", "The source build ID for this redirect rule. Required.") + s.Command.Flags().StringVar(&s.SourceBuildId, "source-build-id", "", "Source Build ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "source-build-id") - s.Command.Flags().StringVar(&s.TargetBuildId, "target-build-id", "", "The target build ID for this redirect rule. Required.") + s.Command.Flags().StringVar(&s.TargetBuildId, "target-build-id", "", "Target Build ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "target-build-id") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Skip confirmation.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1839,10 +1935,10 @@ type ClientOptions struct { GrpcMeta []string Tls bool TlsCertPath string - TlsKeyPath string - TlsCaPath string TlsCertData string + TlsKeyPath string TlsKeyData string + TlsCaPath string TlsCaData string TlsDisableHostVerification bool TlsServerName string @@ -1851,34 +1947,34 @@ type ClientOptions struct { } func (v *ClientOptions) buildFlags(cctx *CommandContext, f *pflag.FlagSet) { - f.StringVar(&v.Address, "address", "127.0.0.1:7233", "Temporal server address.") + f.StringVar(&v.Address, "address", "127.0.0.1:7233", "Temporal Service gRPC endpoint.") cctx.BindFlagEnvVar(f.Lookup("address"), "TEMPORAL_ADDRESS") - f.StringVarP(&v.Namespace, "namespace", "n", "default", "Temporal server namespace.") + f.StringVarP(&v.Namespace, "namespace", "n", "default", "Temporal Service Namespace.") cctx.BindFlagEnvVar(f.Lookup("namespace"), "TEMPORAL_NAMESPACE") - f.StringVar(&v.ApiKey, "api-key", "", "Sets the API key on requests.") + f.StringVar(&v.ApiKey, "api-key", "", "API key for request.") cctx.BindFlagEnvVar(f.Lookup("api-key"), "TEMPORAL_API_KEY") - f.StringArrayVar(&v.GrpcMeta, "grpc-meta", nil, "HTTP headers to send with requests (formatted as key=value).") - f.BoolVar(&v.Tls, "tls", false, "Enable TLS encryption without additional options such as mTLS or client certificates.") + 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.") + f.BoolVar(&v.Tls, "tls", false, "Enable base TLS encryption. Does not have additional options like mTLS or client certs.") cctx.BindFlagEnvVar(f.Lookup("tls"), "TEMPORAL_TLS") - f.StringVar(&v.TlsCertPath, "tls-cert-path", "", "Path to x509 certificate.") + f.StringVar(&v.TlsCertPath, "tls-cert-path", "", "Path to x509 certificate. Can't be used with --tls-cert-data.") cctx.BindFlagEnvVar(f.Lookup("tls-cert-path"), "TEMPORAL_TLS_CERT") - f.StringVar(&v.TlsKeyPath, "tls-key-path", "", "Path to private certificate key.") - cctx.BindFlagEnvVar(f.Lookup("tls-key-path"), "TEMPORAL_TLS_KEY") - f.StringVar(&v.TlsCaPath, "tls-ca-path", "", "Path to server CA certificate.") - cctx.BindFlagEnvVar(f.Lookup("tls-ca-path"), "TEMPORAL_TLS_CA") - f.StringVar(&v.TlsCertData, "tls-cert-data", "", "Data for x509 certificate. Exclusive with -path variant.") + f.StringVar(&v.TlsCertData, "tls-cert-data", "", "Data for x509 certificate. Can't be used with --tls-cert-path.") cctx.BindFlagEnvVar(f.Lookup("tls-cert-data"), "TEMPORAL_TLS_CERT_DATA") - f.StringVar(&v.TlsKeyData, "tls-key-data", "", "Data for private certificate key. Exclusive with -path variant.") + f.StringVar(&v.TlsKeyPath, "tls-key-path", "", "Path to x509 private key. Can't be used with --tls-key-data.") + cctx.BindFlagEnvVar(f.Lookup("tls-key-path"), "TEMPORAL_TLS_KEY") + f.StringVar(&v.TlsKeyData, "tls-key-data", "", "Private certificate key data. Can't be used with --tls-key-path.") cctx.BindFlagEnvVar(f.Lookup("tls-key-data"), "TEMPORAL_TLS_KEY_DATA") - f.StringVar(&v.TlsCaData, "tls-ca-data", "", "Data for server CA certificate. Exclusive with -path variant.") + f.StringVar(&v.TlsCaPath, "tls-ca-path", "", "Path to server CA certificate. Can't be used with --tls-ca-data.") + cctx.BindFlagEnvVar(f.Lookup("tls-ca-path"), "TEMPORAL_TLS_CA") + f.StringVar(&v.TlsCaData, "tls-ca-data", "", "Data for server CA certificate. Can't be used with --tls-ca-path.") cctx.BindFlagEnvVar(f.Lookup("tls-ca-data"), "TEMPORAL_TLS_CA_DATA") - f.BoolVar(&v.TlsDisableHostVerification, "tls-disable-host-verification", false, "Disables TLS host-name verification.") + f.BoolVar(&v.TlsDisableHostVerification, "tls-disable-host-verification", false, "Disable TLS host-name verification.") cctx.BindFlagEnvVar(f.Lookup("tls-disable-host-verification"), "TEMPORAL_TLS_DISABLE_HOST_VERIFICATION") - f.StringVar(&v.TlsServerName, "tls-server-name", "", "Overrides target TLS server name.") + f.StringVar(&v.TlsServerName, "tls-server-name", "", "Override target TLS server name.") cctx.BindFlagEnvVar(f.Lookup("tls-server-name"), "TEMPORAL_TLS_SERVER_NAME") - f.StringVar(&v.CodecEndpoint, "codec-endpoint", "", "Endpoint for a remote Codec Server.") + f.StringVar(&v.CodecEndpoint, "codec-endpoint", "", "Remote Codec Server endpoint.") cctx.BindFlagEnvVar(f.Lookup("codec-endpoint"), "TEMPORAL_CODEC_ENDPOINT") - f.StringVar(&v.CodecAuth, "codec-auth", "", "Sets the authorization header on requests to the Codec Server.") + f.StringVar(&v.CodecAuth, "codec-auth", "", "Authorization header for Codec Server requests.") cctx.BindFlagEnvVar(f.Lookup("codec-auth"), "TEMPORAL_CODEC_AUTH") } @@ -1892,11 +1988,11 @@ func NewTemporalWorkflowCommand(cctx *CommandContext, parent *TemporalCommand) * var s TemporalWorkflowCommand s.Parent = parent s.Command.Use = "workflow" - s.Command.Short = "Start, list, and operate on Workflows." + s.Command.Short = "Start, list, and operate on Workflows" if hasHighlighting { - s.Command.Long = "Workflow commands perform operations on Workflow Executions.\n\nWorkflow commands use this syntax: \x1b[1mtemporal workflow COMMAND [ARGS]\x1b[0m." + s.Command.Long = "Workflow commands perform operations on Workflow Executions:\n\n\x1b[1mtemporal workflow [command] [options]\x1b[0m\n\nFor example:\n\n\x1b[1mtemporal workflow list\x1b[0m" } else { - s.Command.Long = "Workflow commands perform operations on Workflow Executions.\n\nWorkflow commands use this syntax: `temporal workflow COMMAND [ARGS]`." + s.Command.Long = "Workflow commands perform operations on Workflow Executions:\n\n```\ntemporal workflow [command] [options]\n```\n\nFor example:\n\n```\ntemporal workflow list\n```" } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalWorkflowCancelCommand(cctx, &s).Command) @@ -1930,11 +2026,11 @@ func NewTemporalWorkflowCancelCommand(cctx *CommandContext, parent *TemporalWork s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "cancel [flags]" - s.Command.Short = "Cancel a Workflow Execution." + s.Command.Short = "Send cancellation to Workflow Execution" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow cancel\x1b[0m command is used to cancel a Workflow Execution.\nCanceling a running Workflow Execution records a \x1b[1mWorkflowExecutionCancelRequested\x1b[0m event in the Event History. A new\nCommand Task will be scheduled, and the Workflow Execution will perform cleanup work.\n\nExecutions may be cancelled by ID:\n\x1b[1mtemporal workflow cancel --workflow-id MyWorkflowId\x1b[0m\n\n...or in bulk via a visibility query list filter:\n\x1b[1mtemporal workflow cancel --query=MyQuery\x1b[0m\n\nUse the options listed below to change the behavior of this command." + s.Command.Long = "Canceling a running Workflow Execution records a\n\x1b[1mWorkflowExecutionCancelRequested\x1b[0m event in the Event History. The Service\nschedules a new Command Task, and the Workflow Execution performs any cleanup\nwork supported by its implementation.\n\nUse the Workflow ID to cancel an Execution:\n\n\x1b[1mtemporal workflow cancel \\\n --workflow-id YourWorkflowId\x1b[0m\n\nA visibility Query lets you send bulk cancellations to Workflow Executions\nmatching the results:\n\n\x1b[1mtemporal workflow cancel \\\n --query YourQuery\x1b[0m\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See \x1b[1mtemporal batch --help\x1b[0m for a quick reference." } else { - s.Command.Long = "The `temporal workflow cancel` command is used to cancel a Workflow Execution.\nCanceling a running Workflow Execution records a `WorkflowExecutionCancelRequested` event in the Event History. A new\nCommand Task will be scheduled, and the Workflow Execution will perform cleanup work.\n\nExecutions may be cancelled by ID:\n```\ntemporal workflow cancel --workflow-id MyWorkflowId\n```\n\n...or in bulk via a visibility query list filter:\n```\ntemporal workflow cancel --query=MyQuery\n```\n\nUse the options listed below to change the behavior of this command." + s.Command.Long = "Canceling a running Workflow Execution records a\n`WorkflowExecutionCancelRequested` event in the Event History. The Service\nschedules a new Command Task, and the Workflow Execution performs any cleanup\nwork supported by its implementation.\n\nUse the Workflow ID to cancel an Execution:\n\n```\ntemporal workflow cancel \\\n --workflow-id YourWorkflowId\n```\n\nA visibility Query lets you send bulk cancellations to Workflow Executions\nmatching the results:\n\n```\ntemporal workflow cancel \\\n --query YourQuery\n```\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See `temporal batch --help` for a quick reference." } s.Command.Args = cobra.NoArgs s.SingleWorkflowOrBatchOptions.buildFlags(cctx, s.Command.Flags()) @@ -1957,14 +2053,14 @@ func NewTemporalWorkflowCountCommand(cctx *CommandContext, parent *TemporalWorkf s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "count [flags]" - s.Command.Short = "Count Workflow Executions." + s.Command.Short = "Number of Workflow Executions" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow count\x1b[0m command returns a count of Workflow Executions.\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Show a count of Workflow Executions, regardless of execution state (running,\nterminated, etc). Use \x1b[1m--query\x1b[0m to select a subset of Workflow Executions:\n\n\x1b[1mtemporal workflow count \\\n --query YourQuery\x1b[0m\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See \x1b[1mtemporal batch --help\x1b[0m for a quick reference." } else { - s.Command.Long = "The `temporal workflow count` command returns a count of Workflow Executions.\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Show a count of Workflow Executions, regardless of execution state (running,\nterminated, etc). Use `--query` to select a subset of Workflow Executions:\n\n```\ntemporal workflow count \\\n --query YourQuery\n```\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See `temporal batch --help` for a quick reference." } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.Query, "query", "q", "", "Filter results using a SQL-like query.") + s.Command.Flags().StringVarP(&s.Query, "query", "q", "", "Content for an SQL-like `QUERY` List Filter.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1984,11 +2080,11 @@ func NewTemporalWorkflowDeleteCommand(cctx *CommandContext, parent *TemporalWork s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "delete [flags]" - s.Command.Short = "Deletes a Workflow Execution." + s.Command.Short = "Remove Workflow Execution" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow delete\x1b[0m command is used to delete a specific Workflow Execution.\nThis asynchronously deletes a workflow's Event History.\nIf the Workflow Execution is Running, it will be terminated before deletion.\n\n\x1b[1mtemporal workflow delete \\\n\t\t--workflow-id MyWorkflowId \\\x1b[0m\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Delete a Workflow Executions and its Event History:\n\n\x1b[1mtemporal workflow delete \\\n --workflow-id YourWorkflowId\x1b[0m\n\nThe removal executes asynchronously. If the Execution is Running, the Service\nterminates it before deletion.\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See \x1b[1mtemporal batch --help\x1b[0m for a quick reference." } else { - s.Command.Long = "The `temporal workflow delete` command is used to delete a specific Workflow Execution.\nThis asynchronously deletes a workflow's Event History.\nIf the Workflow Execution is Running, it will be terminated before deletion.\n\n```\ntemporal workflow delete \\\n\t\t--workflow-id MyWorkflowId \\\n```\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Delete a Workflow Executions and its Event History:\n\n```\ntemporal workflow delete \\\n --workflow-id YourWorkflowId\n```\n\nThe removal executes asynchronously. If the Execution is Running, the Service\nterminates it before deletion.\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See `temporal batch --help` for a quick reference." } s.Command.Args = cobra.NoArgs s.SingleWorkflowOrBatchOptions.buildFlags(cctx, s.Command.Flags()) @@ -2006,9 +2102,9 @@ type WorkflowReferenceOptions struct { } func (v *WorkflowReferenceOptions) buildFlags(cctx *CommandContext, f *pflag.FlagSet) { - f.StringVarP(&v.WorkflowId, "workflow-id", "w", "", "Workflow Id. Required.") + f.StringVarP(&v.WorkflowId, "workflow-id", "w", "", "Workflow ID. Required.") _ = cobra.MarkFlagRequired(f, "workflow-id") - f.StringVarP(&v.RunId, "run-id", "r", "", "Run Id.") + f.StringVarP(&v.RunId, "run-id", "r", "", "Run ID.") } type TemporalWorkflowDescribeCommand struct { @@ -2024,16 +2120,16 @@ func NewTemporalWorkflowDescribeCommand(cctx *CommandContext, parent *TemporalWo s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "describe [flags]" - s.Command.Short = "Show information about a Workflow Execution." + s.Command.Short = "Show Workflow Execution info" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow describe\x1b[0m command shows information about a given\nWorkflow Execution.\n\nThis information can be used to locate Workflow Executions that weren't able to run successfully.\n\n\x1b[1mtemporal workflow describe --workflow-id=meaningful-business-id\x1b[0m\n\nOutput can be shown as printed ('raw') or formatted to only show the Workflow Execution's auto-reset points.\n\n\x1b[1mtemporal workflow describe --workflow-id=meaningful-business-id --raw=true --reset-points=true\x1b[0m\n\nUse the command options below to change the information returned by this command." + s.Command.Long = "Display information about a specific Workflow Execution:\n\n\x1b[1mtemporal workflow describe \\\n --workflow-id YourWorkflowId\x1b[0m\n\nShow the Workflow Execution's auto-reset points:\n\n\x1b[1mtemporal workflow describe \\\n --workflow-id YourWorkflowId \\\n --reset-points true\x1b[0m" } else { - s.Command.Long = "The `temporal workflow describe` command shows information about a given\nWorkflow Execution.\n\nThis information can be used to locate Workflow Executions that weren't able to run successfully.\n\n`temporal workflow describe --workflow-id=meaningful-business-id`\n\nOutput can be shown as printed ('raw') or formatted to only show the Workflow Execution's auto-reset points.\n\n`temporal workflow describe --workflow-id=meaningful-business-id --raw=true --reset-points=true`\n\nUse the command options below to change the information returned by this command." + s.Command.Long = "Display information about a specific Workflow Execution:\n\n```\ntemporal workflow describe \\\n --workflow-id YourWorkflowId\n```\n\nShow the Workflow Execution's auto-reset points:\n\n```\ntemporal workflow describe \\\n --workflow-id YourWorkflowId \\\n --reset-points true\n```" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().BoolVar(&s.ResetPoints, "reset-points", false, "Only show auto-reset points.") - s.Command.Flags().BoolVar(&s.Raw, "raw", false, "Print properties without changing their format.") + s.Command.Flags().BoolVar(&s.ResetPoints, "reset-points", false, "Show auto-reset points only.") + s.Command.Flags().BoolVar(&s.Raw, "raw", false, "Print properties without changing their format. Defaults to true.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -2056,17 +2152,17 @@ func NewTemporalWorkflowExecuteCommand(cctx *CommandContext, parent *TemporalWor s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "execute [flags]" - s.Command.Short = "Start a new Workflow Execution and prints its progress." + s.Command.Short = "Start new Workflow Execution" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow execute\x1b[0m command starts a new Workflow Execution and\nprints its progress. The command completes when the Workflow Execution completes.\n\nSingle quotes('') are used to wrap input as JSON.\n\n\x1b[1mtemporal workflow execute\n\t\t--workflow-id meaningful-business-id \\\n\t\t--type MyWorkflow \\\n\t\t--task-queue MyTaskQueue \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\x1b[0m" + s.Command.Long = "Establish a new Workflow Execution and direct its progress to stdout. The\ncommand blocks and returns when the Workflow Execution completes. If your\nWorkflow requires input, pass valid JSON:\n\n\x1b[1mtemporal workflow execute\n --workflow-id YourWorkflowId \\\n --type YourWorkflow \\\n --task-queue YourTaskQueue \\\n --input '{\"Input\": \"As-JSON\"}'\x1b[0m\n\nUse \x1b[1m--event-details\x1b[0m to relay updates to the command-line output in JSON\nformat. When using JSON output (\x1b[1m--output json\x1b[0m), this includes the entire\n\"history\" JSON key for the run." } else { - s.Command.Long = "The `temporal workflow execute` command starts a new Workflow Execution and\nprints its progress. The command completes when the Workflow Execution completes.\n\nSingle quotes('') are used to wrap input as JSON.\n\n```\ntemporal workflow execute\n\t\t--workflow-id meaningful-business-id \\\n\t\t--type MyWorkflow \\\n\t\t--task-queue MyTaskQueue \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\n```" + s.Command.Long = "Establish a new Workflow Execution and direct its progress to stdout. The\ncommand blocks and returns when the Workflow Execution completes. If your\nWorkflow requires input, pass valid JSON:\n\n```\ntemporal workflow execute\n --workflow-id YourWorkflowId \\\n --type YourWorkflow \\\n --task-queue YourTaskQueue \\\n --input '{\"Input\": \"As-JSON\"}'\n```\n\nUse `--event-details` to relay updates to the command-line output in JSON\nformat. When using JSON output (`--output json`), this includes the entire\n\"history\" JSON key for the run." } s.Command.Args = cobra.NoArgs s.SharedWorkflowStartOptions.buildFlags(cctx, s.Command.Flags()) s.WorkflowStartOptions.buildFlags(cctx, s.Command.Flags()) s.PayloadInputOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().BoolVar(&s.Detailed, "detailed", false, "If set when using text output, display events as sections with detail instead of simple table. If set when using JSON output, this will include the entire \"history\" JSON key of the started run (does not follow runs).") + s.Command.Flags().BoolVar(&s.Detailed, "detailed", false, "Display events as sections instead of table. Does not apply to JSON output.") s.Command.Flags().SetNormalizeFunc(aliasNormalizer(map[string]string{ "name": "type", })) @@ -2090,16 +2186,16 @@ func NewTemporalWorkflowFixHistoryJsonCommand(cctx *CommandContext, parent *Temp s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "fix-history-json [flags]" - s.Command.Short = "Updates an event history JSON file to the current format." + s.Command.Short = "Updates an event history JSON file" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal workflow fix-history-json \\\n\t--source original.json \\\n\t--target reserialized.json\x1b[0m\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Reserialize an Event History JSON file:\n\n\x1b[1mtemporal workflow fix-history-json \\\n\t--source /path/to/original.json \\\n\t--target /path/to/reserialized.json\x1b[0m" } else { - s.Command.Long = "```\ntemporal workflow fix-history-json \\\n\t--source original.json \\\n\t--target reserialized.json\n```\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Reserialize an Event History JSON file:\n\n```\ntemporal workflow fix-history-json \\\n\t--source /path/to/original.json \\\n\t--target /path/to/reserialized.json\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.Source, "source", "s", "", "Path to the input file. Required.") + s.Command.Flags().StringVarP(&s.Source, "source", "s", "", "Path to the original file. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "source") - s.Command.Flags().StringVarP(&s.Target, "target", "t", "", "Path to the output file, or standard output if not set.") + s.Command.Flags().StringVarP(&s.Target, "target", "t", "", "Path to the results file. When omitted, output is sent to stdout.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -2121,16 +2217,16 @@ func NewTemporalWorkflowListCommand(cctx *CommandContext, parent *TemporalWorkfl s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "list [flags]" - s.Command.Short = "List Workflow Executions based on a Query." + s.Command.Short = "Show Workflow Executions" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow list\x1b[0m command provides a list of Workflow Executions\nthat meet the criteria of a given Query.\nBy default, this command returns up to 10 closed Workflow Executions.\n\n\x1b[1mtemporal workflow list --query=MyQuery\x1b[0m\n\nThe command can also return a list of archived Workflow Executions.\n\n\x1b[1mtemporal workflow list --archived\x1b[0m\n\nUse the command options below to change the information returned by this command." + s.Command.Long = "List Workflow Executions. By default, this command returns up to 10 closed\nWorkflow Executions. The optional \x1b[1m--query\x1b[0m limits the output to Workflows\nmatching a Query:\n\n\x1b[1mtemporal workflow list \\\n --query YourQuery\x1b[1m\x1b[0m\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See \x1b[0mtemporal batch --help` for a quick reference.\n\nView a list of archived Workflow Executions:\n\n\x1b[1mtemporal workflow list \\\n --archived\x1b[0m" } else { - s.Command.Long = "The `temporal workflow list` command provides a list of Workflow Executions\nthat meet the criteria of a given Query.\nBy default, this command returns up to 10 closed Workflow Executions.\n\n`temporal workflow list --query=MyQuery`\n\nThe command can also return a list of archived Workflow Executions.\n\n`temporal workflow list --archived`\n\nUse the command options below to change the information returned by this command." + s.Command.Long = "List Workflow Executions. By default, this command returns up to 10 closed\nWorkflow Executions. The optional `--query` limits the output to Workflows\nmatching a Query:\n\n```\ntemporal workflow list \\\n --query YourQuery`\n```\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See `temporal batch --help` for a quick reference.\n\nView a list of archived Workflow Executions:\n\n```\ntemporal workflow list \\\n --archived\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.Query, "query", "q", "", "Filter results using a SQL-like query.") - s.Command.Flags().BoolVar(&s.Archived, "archived", false, "If set, will only query and list archived workflows instead of regular workflows.") - s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Limit the number of items to print.") + s.Command.Flags().StringVarP(&s.Query, "query", "q", "", "Content for an SQL-like `QUERY` List Filter.") + s.Command.Flags().BoolVar(&s.Archived, "archived", false, "Limit output to archived Workflow Executions.") + s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Maximum number of Workflow Executions to display.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -2153,11 +2249,11 @@ func NewTemporalWorkflowQueryCommand(cctx *CommandContext, parent *TemporalWorkf s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "query [flags]" - s.Command.Short = "Query a Workflow Execution." + s.Command.Short = "Retrieve Workflow Execution state" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow query\x1b[0m command is used to Query a\nWorkflow Execution\nby ID.\n\n\x1b[1mtemporal workflow query \\\n\t\t--workflow-id MyWorkflowId \\\n\t\t--name MyQuery \\\n\t\t--input '{\"MyInputKey\": \"MyInputValue\"}'\x1b[0m\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Send a Query to a Workflow Execution by Workflow ID to retrieve its state.\nThis synchronous operation exposes the internal state of a running Workflow\nExecution, which constantly changes. You can query both running and completed\nWorkflow Executions:\n\n\x1b[1mtemporal workflow query \\\n --workflow-id YourWorkflowId\n --type YourQueryType\n --input '{\"YourInputKey\": \"YourInputValue\"}'\x1b[0m" } else { - s.Command.Long = "The `temporal workflow query` command is used to Query a\nWorkflow Execution\nby ID.\n\n```\ntemporal workflow query \\\n\t\t--workflow-id MyWorkflowId \\\n\t\t--name MyQuery \\\n\t\t--input '{\"MyInputKey\": \"MyInputValue\"}'\n```\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Send a Query to a Workflow Execution by Workflow ID to retrieve its state.\nThis synchronous operation exposes the internal state of a running Workflow\nExecution, which constantly changes. You can query both running and completed\nWorkflow Executions:\n\n```\ntemporal workflow query \\\n --workflow-id YourWorkflowId\n --type YourQueryType\n --input '{\"YourInputKey\": \"YourInputValue\"}'\n```" } s.Command.Args = cobra.NoArgs s.PayloadInputOptions.buildFlags(cctx, s.Command.Flags()) @@ -2197,26 +2293,26 @@ func NewTemporalWorkflowResetCommand(cctx *CommandContext, parent *TemporalWorkf s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "reset [flags]" - s.Command.Short = "Resets a Workflow Execution by Event ID or reset type." + s.Command.Short = "Move Workflow Execution history point" if hasHighlighting { - s.Command.Long = "The temporal workflow reset command resets a Workflow Execution.\nA reset allows the Workflow to resume from a certain point without losing its parameters or Event History.\n\nThe Workflow Execution can be set to a given Event Type:\n\x1b[1mtemporal workflow reset --workflow-id=meaningful-business-id --type=LastContinuedAsNew\x1b[0m\n\n...or a specific any Event after \x1b[1mWorkflowTaskStarted\x1b[0m.\n\x1b[1mtemporal workflow reset --workflow-id=meaningful-business-id --event-id=MyLastEvent\x1b[0m\nFor batch reset only FirstWorkflowTask, LastWorkflowTask or BuildId can be used. Workflow Id, run Id and event Id\nshould not be set.\nUse the options listed below to change reset behavior." + s.Command.Long = "Reset a Workflow Execution so it can resume from a point in its Event History\nwithout losing its progress up to that point:\n\n\x1b[1mtemporal workflow reset \\\n --workflow-id YourWorkflowId\n --event-id YourLastEvent\x1b[0m\n\nStart from where the Workflow Execution last continued as new:\n\n\x1b[1mtemporal workflow reset \\\n --workflow-id YourWorkflowId \\\n --type LastContinuedAsNew\x1b[0m\n\nFor batch resets, limit your resets to FirstWorkflowTask, LastWorkflowTask, or\nBuildId. Do not use Workflow IDs, run IDs, or event IDs with this command.\n\nVisit https://docs.temporal.io/visibility to read more about Search\nAttributes and Query creation." } else { - s.Command.Long = "The temporal workflow reset command resets a Workflow Execution.\nA reset allows the Workflow to resume from a certain point without losing its parameters or Event History.\n\nThe Workflow Execution can be set to a given Event Type:\n```\ntemporal workflow reset --workflow-id=meaningful-business-id --type=LastContinuedAsNew\n```\n\n...or a specific any Event after `WorkflowTaskStarted`.\n```\ntemporal workflow reset --workflow-id=meaningful-business-id --event-id=MyLastEvent\n```\nFor batch reset only FirstWorkflowTask, LastWorkflowTask or BuildId can be used. Workflow Id, run Id and event Id\nshould not be set.\nUse the options listed below to change reset behavior." + s.Command.Long = "Reset a Workflow Execution so it can resume from a point in its Event History\nwithout losing its progress up to that point:\n\n```\ntemporal workflow reset \\\n --workflow-id YourWorkflowId\n --event-id YourLastEvent\n```\n\nStart from where the Workflow Execution last continued as new:\n\n```\ntemporal workflow reset \\\n --workflow-id YourWorkflowId \\\n --type LastContinuedAsNew\n```\n\nFor batch resets, limit your resets to FirstWorkflowTask, LastWorkflowTask, or\nBuildId. Do not use Workflow IDs, run IDs, or event IDs with this command.\n\nVisit https://docs.temporal.io/visibility to read more about Search\nAttributes and Query creation." } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow Id. Required for non-batch reset operations.") - s.Command.Flags().StringVarP(&s.RunId, "run-id", "r", "", "Run Id.") - s.Command.Flags().IntVarP(&s.EventId, "event-id", "e", 0, "The Event Id for any Event after `WorkflowTaskStarted` you want to reset to (exclusive). It can be `WorkflowTaskCompleted`, `WorkflowTaskFailed` or others.") - s.Command.Flags().StringVar(&s.Reason, "reason", "", "The reason why this workflow is being reset. Required.") + s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow ID. Required for non-batch reset operations.") + s.Command.Flags().StringVarP(&s.RunId, "run-id", "r", "", "Run ID.") + s.Command.Flags().IntVarP(&s.EventId, "event-id", "e", 0, "Event ID to reset to. Event must occur after `WorkflowTaskStarted`. `WorkflowTaskCompleted`, `WorkflowTaskFailed`, etc. are valid.") + s.Command.Flags().StringVar(&s.Reason, "reason", "", "Reason for reset. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "reason") s.ReapplyType = NewStringEnum([]string{"All", "Signal", "None"}, "All") - s.Command.Flags().Var(&s.ReapplyType, "reapply-type", "*DEPRECATED* Use --reapply-exclude. Event types to reapply after the reset point. Accepted values: All, Signal, None.") - s.Command.Flags().StringArrayVar(&s.ReapplyExclude, "reapply-exclude", nil, "Event types to exclude from reapplication. Accepted values: All, Signal, Update.") + s.Command.Flags().Var(&s.ReapplyType, "reapply-type", "Types of events to re-apply after reset point. Deprecated. Use --reapply-exclude instead. Accepted values: All, Signal, None.") + s.Command.Flags().StringArrayVar(&s.ReapplyExclude, "reapply-exclude", nil, "Exclude these event types from re-application. Accepted values: All, Signal, Update.") s.Type = NewStringEnum([]string{"FirstWorkflowTask", "LastWorkflowTask", "LastContinuedAsNew", "BuildId"}, "") - s.Command.Flags().VarP(&s.Type, "type", "t", "Event type to which you want to reset. Accepted values: FirstWorkflowTask, LastWorkflowTask, LastContinuedAsNew, BuildId.") - s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Only used if type is BuildId. Reset the first workflow task processed by this build id. Note that by default, this reset is allowed to be to a prior run in a chain of continue-as-new.") - s.Command.Flags().StringVarP(&s.Query, "query", "q", "", "Start a batch reset to operate on Workflow Executions with given List Filter.") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Confirm prompt to perform batch. Only allowed if query is present.") + s.Command.Flags().VarP(&s.Type, "type", "t", "The event type for the reset. Accepted values: FirstWorkflowTask, LastWorkflowTask, LastContinuedAsNew, BuildId.") + s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "A Build ID. Use only with the BuildId `--type`. Resets the first Workflow task processed by this ID. By default, this reset may be in a prior run, earlier than a Continue as New point.") + s.Command.Flags().StringVarP(&s.Query, "query", "q", "", "Content for an SQL-like `QUERY` List Filter.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm. Only allowed when `--query` is present.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -2238,16 +2334,16 @@ func NewTemporalWorkflowShowCommand(cctx *CommandContext, parent *TemporalWorkfl s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "show [flags]" - s.Command.Short = "Show Event History for a Workflow Execution." + s.Command.Short = "Display Event History" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow show\x1b[0m command provides the Event History for a\nWorkflow Execution. With JSON output specified, this output can be given to\nan SDK to perform a replay.\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Show a Workflow Execution's Event History.\nWhen using JSON output (\x1b[1m--output json\x1b[0m), you may pass the results to an SDK\nto perform a replay:\n\n\x1b[1mtemporal workflow show \\\n --workflow-id YourWorkflowId\n --output json\x1b[0m" } else { - s.Command.Long = "The `temporal workflow show` command provides the Event History for a\nWorkflow Execution. With JSON output specified, this output can be given to\nan SDK to perform a replay.\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Show a Workflow Execution's Event History.\nWhen using JSON output (`--output json`), you may pass the results to an SDK\nto perform a replay:\n\n```\ntemporal workflow show \\\n --workflow-id YourWorkflowId\n --output json\n```" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().BoolVarP(&s.Follow, "follow", "f", false, "Follow the progress of a Workflow Execution in real time (does not apply to JSON output).") - s.Command.Flags().BoolVar(&s.Detailed, "detailed", false, "If set when using text output, display events as sections with detail instead of simple table.") + s.Command.Flags().BoolVarP(&s.Follow, "follow", "f", false, "Follow the Workflow Execution progress in real time. Does not apply to JSON output.") + s.Command.Flags().BoolVar(&s.Detailed, "detailed", false, "Display events as detailed sections instead of table. Does not apply to JSON output.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -2258,18 +2354,18 @@ func NewTemporalWorkflowShowCommand(cctx *CommandContext, parent *TemporalWorkfl type SingleWorkflowOrBatchOptions struct { WorkflowId string - RunId string Query string + RunId string Reason string Yes bool } func (v *SingleWorkflowOrBatchOptions) buildFlags(cctx *CommandContext, f *pflag.FlagSet) { - f.StringVarP(&v.WorkflowId, "workflow-id", "w", "", "Workflow Id. Either this or query must be set.") - f.StringVarP(&v.RunId, "run-id", "r", "", "Run Id. Cannot be set when query is set.") - f.StringVarP(&v.Query, "query", "q", "", "Start a batch to operate on Workflow Executions with given List Filter. Either this or Workflow Id must be set.") - f.StringVar(&v.Reason, "reason", "", "Reason to perform batch. Only allowed if query is present unless the command specifies otherwise. Defaults to message with the current user's name.") - f.BoolVarP(&v.Yes, "yes", "y", false, "Confirm prompt to perform batch. Only allowed if query is present.") + f.StringVarP(&v.WorkflowId, "workflow-id", "w", "", "Workflow ID. You must set either --workflow-id or --query.") + f.StringVarP(&v.Query, "query", "q", "", "Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query.") + f.StringVarP(&v.RunId, "run-id", "r", "", "Run ID. Only use with --workflow-id. Cannot use with --query.") + f.StringVar(&v.Reason, "reason", "", "Reason to perform batch. Only use with --query. Defaults to user name.") + f.BoolVarP(&v.Yes, "yes", "y", false, "Don't prompt to confirm signaling. Only allowed when --query is present.") } type TemporalWorkflowSignalCommand struct { @@ -2285,15 +2381,15 @@ func NewTemporalWorkflowSignalCommand(cctx *CommandContext, parent *TemporalWork s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "signal [flags]" - s.Command.Short = "Signal Workflow Execution by Id." + s.Command.Short = "Send a message to a Workflow Execution" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow signal\x1b[0m command is used to Signal a\nWorkflow Execution by ID.\n\n\x1b[1mtemporal workflow signal \\\n\t\t--workflow-id MyWorkflowId \\\n\t\t--name MySignal \\\n\t\t--input '{\"MyInputKey\": \"MyInputValue\"}'\x1b[0m\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Send an asynchronous notification (Signal) to a running Workflow Execution by\nits Workflow ID. The Signal is written to the History. When you include\n\x1b[1m--input\x1b[0m, that data is available for the Workflow Execution to consume:\n\n\x1b[1mtemporal workflow signal \\\n\t\t--workflow-id YourWorkflowId \\\n\t\t--name YourSignal \\\n\t\t--input '{\"YourInputKey\": \"YourInputValue\"}'\x1b[0m\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See \x1b[1mtemporal batch --help\x1b[0m for a quick reference." } else { - s.Command.Long = "The `temporal workflow signal` command is used to Signal a\nWorkflow Execution by ID.\n\n```\ntemporal workflow signal \\\n\t\t--workflow-id MyWorkflowId \\\n\t\t--name MySignal \\\n\t\t--input '{\"MyInputKey\": \"MyInputValue\"}'\n```\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Send an asynchronous notification (Signal) to a running Workflow Execution by\nits Workflow ID. The Signal is written to the History. When you include\n`--input`, that data is available for the Workflow Execution to consume:\n\n```\ntemporal workflow signal \\\n\t\t--workflow-id YourWorkflowId \\\n\t\t--name YourSignal \\\n\t\t--input '{\"YourInputKey\": \"YourInputValue\"}'\n```\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See `temporal batch --help` for a quick reference." } s.Command.Args = cobra.NoArgs s.PayloadInputOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().StringVar(&s.Name, "name", "", "Signal Name. Required. Aliased as \"--type\".") + s.Command.Flags().StringVar(&s.Name, "name", "", "Signal name. Required. Aliased as \"--type\".") _ = cobra.MarkFlagRequired(s.Command.Flags(), "name") s.SingleWorkflowOrBatchOptions.buildFlags(cctx, s.Command.Flags()) s.Command.Flags().SetNormalizeFunc(aliasNormalizer(map[string]string{ @@ -2319,16 +2415,16 @@ func NewTemporalWorkflowStackCommand(cctx *CommandContext, parent *TemporalWorkf s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "stack [flags]" - s.Command.Short = "Query a Workflow Execution for its stack trace." + s.Command.Short = "Trace a Workflow Execution" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow stack\x1b[0m command Queries a\nWorkflow Execution with \x1b[1m__stack_trace\x1b[0m as the query type.\nThis returns a stack trace of all the threads or routines currently used by the workflow, and is\nuseful for troubleshooting.\n\n\x1b[1mtemporal workflow stack --workflow-id MyWorkflowId\x1b[0m\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Perform a Query on a Workflow Execution using a \x1b[1m__stack_trace\x1b[0m-type Query.\nDisplay a stack trace of the threads and routines currently in use by the\nWorkflow for troubleshooting:\n\n\x1b[1mtemporal workflow stack \\\n --workflow-id YourWorkflowId\x1b[0m" } else { - s.Command.Long = "The `temporal workflow stack` command Queries a\nWorkflow Execution with `__stack_trace` as the query type.\nThis returns a stack trace of all the threads or routines currently used by the workflow, and is\nuseful for troubleshooting.\n\n```\ntemporal workflow stack --workflow-id MyWorkflowId\n```\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Perform a Query on a Workflow Execution using a `__stack_trace`-type Query.\nDisplay a stack trace of the threads and routines currently in use by the\nWorkflow for troubleshooting:\n\n```\ntemporal workflow stack \\\n --workflow-id YourWorkflowId\n```" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) s.RejectCondition = NewStringEnum([]string{"not_open", "not_completed_cleanly"}, "") - s.Command.Flags().Var(&s.RejectCondition, "reject-condition", "Optional flag for rejecting Queries based on Workflow state. Accepted values: not_open, not_completed_cleanly.") + s.Command.Flags().Var(&s.RejectCondition, "reject-condition", "Optional flag to reject Queries based on Workflow state. Accepted values: not_open, not_completed_cleanly.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -2349,19 +2445,19 @@ type SharedWorkflowStartOptions struct { } func (v *SharedWorkflowStartOptions) buildFlags(cctx *CommandContext, f *pflag.FlagSet) { - f.StringVarP(&v.WorkflowId, "workflow-id", "w", "", "Workflow Id.") + f.StringVarP(&v.WorkflowId, "workflow-id", "w", "", "Workflow ID. If not supplied, the Service generates a unique ID.") f.StringVar(&v.Type, "type", "", "Workflow Type name. Required. Aliased as \"--name\".") _ = cobra.MarkFlagRequired(f, "type") f.StringVarP(&v.TaskQueue, "task-queue", "t", "", "Workflow Task queue. Required.") _ = cobra.MarkFlagRequired(f, "task-queue") v.RunTimeout = 0 - f.Var(&v.RunTimeout, "run-timeout", "Timeout of a Workflow Run.") + f.Var(&v.RunTimeout, "run-timeout", "Fail a Workflow Run if it lasts longer than `DURATION`.") v.ExecutionTimeout = 0 - f.Var(&v.ExecutionTimeout, "execution-timeout", "Timeout for a WorkflowExecution, including retries and ContinueAsNew tasks.") + f.Var(&v.ExecutionTimeout, "execution-timeout", "Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks.") v.TaskTimeout = Duration(10000 * time.Millisecond) - f.Var(&v.TaskTimeout, "task-timeout", "Start-to-close timeout for a Workflow Task.") - f.StringArrayVar(&v.SearchAttribute, "search-attribute", nil, "Passes Search Attribute in key=value format. Use valid JSON formats for value.") - f.StringArrayVar(&v.Memo, "memo", nil, "Passes Memo in key=value format. Use valid JSON formats for value.") + f.Var(&v.TaskTimeout, "task-timeout", "Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task.") + f.StringArrayVar(&v.SearchAttribute, "search-attribute", nil, "Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: 'YourKey={\"your\": \"value\"}'. Can be passed multiple times.") + f.StringArrayVar(&v.Memo, "memo", nil, "Memo using 'KEY=\"VALUE\"' pairs. Use JSON values.") } type WorkflowStartOptions struct { @@ -2372,11 +2468,11 @@ type WorkflowStartOptions struct { } func (v *WorkflowStartOptions) buildFlags(cctx *CommandContext, f *pflag.FlagSet) { - f.StringVar(&v.Cron, "cron", "", "Cron schedule for the workflow. Deprecated - use schedules instead.") - f.BoolVar(&v.FailExisting, "fail-existing", false, "Fail if the workflow already exists.") + f.StringVar(&v.Cron, "cron", "", "Cron schedule for the Workflow. Deprecated. Use Schedules instead.") + f.BoolVar(&v.FailExisting, "fail-existing", false, "Fail if the Workflow already exists.") v.StartDelay = 0 - f.Var(&v.StartDelay, "start-delay", "Specify a delay before the workflow starts. Cannot be used with a cron schedule. If the workflow receives a signal or update before the delay has elapsed, it will begin immediately.") - f.StringVar(&v.IdReusePolicy, "id-reuse-policy", "", "Allows the same Workflow Id to be used in a new Workflow Execution. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning.") + f.Var(&v.StartDelay, "start-delay", "Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately.") + f.StringVar(&v.IdReusePolicy, "id-reuse-policy", "", "Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning.") } type PayloadInputOptions struct { @@ -2387,10 +2483,10 @@ type PayloadInputOptions struct { } func (v *PayloadInputOptions) buildFlags(cctx *CommandContext, f *pflag.FlagSet) { - f.StringArrayVarP(&v.Input, "input", "i", nil, "Input value (default JSON unless --input-payload-meta is non-JSON encoding). Can be given multiple times for multiple arguments. Cannot be combined with --input-file.") - f.StringArrayVar(&v.InputFile, "input-file", nil, "Reads a file as the input (JSON by default unless --input-payload-meta is non-JSON encoding). Can be given multiple times for multiple arguments. Cannot be combined with --input.") - f.StringArrayVar(&v.InputMeta, "input-meta", nil, "Metadata for the input payload. Expected as key=value. If key is encoding, overrides the default of json/plain.") - f.BoolVar(&v.InputBase64, "input-base64", false, "If set, assumes --input or --input-file are base64 encoded and attempts to decode.") + f.StringArrayVarP(&v.Input, "input", "i", nil, "Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.") + f.StringArrayVar(&v.InputFile, "input-file", nil, "A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.") + f.StringArrayVar(&v.InputMeta, "input-meta", nil, "Input payload metadata as a `KEY=VALUE` pair. When the KEY is \"encoding\", this overrides the default (\"json/plain\"). Can be passed multiple times.") + f.BoolVar(&v.InputBase64, "input-base64", false, "Assume inputs are base64-encoded and attempt to decode them.") } type TemporalWorkflowStartCommand struct { @@ -2406,11 +2502,11 @@ func NewTemporalWorkflowStartCommand(cctx *CommandContext, parent *TemporalWorkf s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "start [flags]" - s.Command.Short = "Starts a new Workflow Execution." + s.Command.Short = "Initiate a Workflow Execution" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow start\x1b[0m command starts a new Workflow Execution. The\nWorkflow and Run IDs are returned after starting the Workflow.\n\n\x1b[1mtemporal workflow start \\\n\t\t--workflow-id meaningful-business-id \\\n\t\t--type MyWorkflow \\\n\t\t--task-queue MyTaskQueue \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\x1b[0m" + s.Command.Long = "Start a new Workflow Execution. Returns the Workflow- and Run-IDs.\n\n\x1b[1mtemporal workflow start \\\n\t\t--workflow-id YourWorkflowId \\\n\t\t--type YourWorkflow \\\n\t\t--task-queue YourTaskQueue \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\x1b[0m" } else { - s.Command.Long = "The `temporal workflow start` command starts a new Workflow Execution. The\nWorkflow and Run IDs are returned after starting the Workflow.\n\n```\ntemporal workflow start \\\n\t\t--workflow-id meaningful-business-id \\\n\t\t--type MyWorkflow \\\n\t\t--task-queue MyTaskQueue \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\n```" + s.Command.Long = "Start a new Workflow Execution. Returns the Workflow- and Run-IDs.\n\n```\ntemporal workflow start \\\n\t\t--workflow-id YourWorkflowId \\\n\t\t--type YourWorkflow \\\n\t\t--task-queue YourTaskQueue \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\n```" } s.Command.Args = cobra.NoArgs s.SharedWorkflowStartOptions.buildFlags(cctx, s.Command.Flags()) @@ -2431,8 +2527,8 @@ type TemporalWorkflowTerminateCommand struct { Parent *TemporalWorkflowCommand Command cobra.Command WorkflowId string - RunId string Query string + RunId string Reason string Yes bool } @@ -2442,18 +2538,18 @@ func NewTemporalWorkflowTerminateCommand(cctx *CommandContext, parent *TemporalW s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "terminate [flags]" - s.Command.Short = "Terminate Workflow Execution by ID or List Filter." + s.Command.Short = "Forcefully end a Workflow Execution" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow terminate\x1b[0m command is used to terminate a\nWorkflow Execution. Canceling a running Workflow Execution records a\n\x1b[1mWorkflowExecutionTerminated\x1b[0m event as the closing Event in the workflow's Event History. Workflow code is oblivious to\ntermination. Use \x1b[1mtemporal workflow cancel\x1b[0m if you need to perform cleanup in your workflow.\n\nExecutions may be terminated by ID with an optional reason:\n\x1b[1mtemporal workflow terminate [--reason my-reason] --workflow-id MyWorkflowId\x1b[0m\n\n...or in bulk via a visibility query list filter:\n\x1b[1mtemporal workflow terminate --query=MyQuery\x1b[0m\n\nUse the options listed below to change the behavior of this command." + s.Command.Long = "Terminate a Workflow Execution:\n\n\x1b[1mtemporal workflow terminate \\\n --reason YourReasonForTermination \\\n --workflow-id YourWorkflowId\x1b[0m\n\nThe reason is optional and defaults to the current user's name. The reason\nis stored in the Event History as part of the \x1b[1mWorkflowExecutionTerminated\x1b[0m\nevent. This becomes the closing Event in the Workflow Execution's history.\n\nExecutions may be terminated in bulk via a visibility Query list filter:\n\n\x1b[1mtemporal workflow terminate \\\n --query YourQuery \\\n --reason YourReasonForTermination\x1b[0m\n\nWorkflow code cannot see or respond to terminations. To perform clean-up work\nin your Workflow code, use \x1b[1mtemporal workflow cancel\x1b[0m instead.\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See \x1b[1mtemporal batch --help\x1b[0m for a quick reference." } else { - s.Command.Long = "The `temporal workflow terminate` command is used to terminate a\nWorkflow Execution. Canceling a running Workflow Execution records a\n`WorkflowExecutionTerminated` event as the closing Event in the workflow's Event History. Workflow code is oblivious to\ntermination. Use `temporal workflow cancel` if you need to perform cleanup in your workflow.\n\nExecutions may be terminated by ID with an optional reason:\n```\ntemporal workflow terminate [--reason my-reason] --workflow-id MyWorkflowId\n```\n\n...or in bulk via a visibility query list filter:\n```\ntemporal workflow terminate --query=MyQuery\n```\n\nUse the options listed below to change the behavior of this command." + s.Command.Long = "Terminate a Workflow Execution:\n\n```\ntemporal workflow terminate \\\n --reason YourReasonForTermination \\\n --workflow-id YourWorkflowId\n```\n\nThe reason is optional and defaults to the current user's name. The reason\nis stored in the Event History as part of the `WorkflowExecutionTerminated`\nevent. This becomes the closing Event in the Workflow Execution's history.\n\nExecutions may be terminated in bulk via a visibility Query list filter:\n\n```\ntemporal workflow terminate \\\n --query YourQuery \\\n --reason YourReasonForTermination\n```\n\nWorkflow code cannot see or respond to terminations. To perform clean-up work\nin your Workflow code, use `temporal workflow cancel` instead.\n\nVisit https://docs.temporal.io/visibility to read more about Search Attributes\nand Query creation. See `temporal batch --help` for a quick reference." } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow Id. Either this or query must be set.") - s.Command.Flags().StringVarP(&s.RunId, "run-id", "r", "", "Run Id. Cannot be set when query is set.") - s.Command.Flags().StringVarP(&s.Query, "query", "q", "", "Start a batch to terminate Workflow Executions with given List Filter. Either this or Workflow Id must be set.") + s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow ID. You must set either --workflow-id or --query.") + s.Command.Flags().StringVarP(&s.Query, "query", "q", "", "Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query.") + s.Command.Flags().StringVarP(&s.RunId, "run-id", "r", "", "Run ID. Can only be set with --workflow-id. Do not use with --query.") s.Command.Flags().StringVar(&s.Reason, "reason", "", "Reason for termination. Defaults to message with the current user's name.") - s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Confirm prompt to perform batch. Only allowed if query is present.") + s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm termination. Can only be used with --query.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -2477,18 +2573,18 @@ func NewTemporalWorkflowTraceCommand(cctx *CommandContext, parent *TemporalWorkf s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "trace [flags]" - s.Command.Short = "Terminate Workflow Execution by ID or List Filter." + s.Command.Short = "Workflow Execution live progress" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow trace\x1b[0m command display the progress of a Workflow Execution and its child workflows with a trace.\nThis view provides a great way to understand the flow of a workflow.\n\nUse the options listed below to change the behavior of this command." + s.Command.Long = "Display the progress of a Workflow Execution and its child workflows with a\nreal-time trace. This view helps you understand how Workflows are proceeding:\n\n\x1b[1mtemporal workflow trace \\\n --workflow-id YourWorkflowId\x1b[0m" } else { - s.Command.Long = "The `temporal workflow trace` command display the progress of a Workflow Execution and its child workflows with a trace.\nThis view provides a great way to understand the flow of a workflow.\n\nUse the options listed below to change the behavior of this command." + s.Command.Long = "Display the progress of a Workflow Execution and its child workflows with a\nreal-time trace. This view helps you understand how Workflows are proceeding:\n\n```\ntemporal workflow trace \\\n --workflow-id YourWorkflowId\n```" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().StringArrayVar(&s.Fold, "fold", nil, "Statuses for which Child Workflows will be folded in (this will reduce the number of information fetched and displayed). Case-insensitive and ignored if no-fold supplied. Available values: running, completed, failed, canceled, terminated, timedout, continueasnew.") - s.Command.Flags().BoolVar(&s.NoFold, "no-fold", false, "Disable folding. All Child Workflows within the set depth will be fetched and displayed.") - s.Command.Flags().IntVar(&s.Depth, "depth", -1, "Depth of child workflows to fetch. Use -1 to fetch child workflows at any depth.") - s.Command.Flags().IntVar(&s.Concurrency, "concurrency", 10, "Number of concurrent workflow histories that will be requested at any given time.") + s.Command.Flags().StringArrayVar(&s.Fold, "fold", nil, "Fold away Child Workflows with the specified statuses. Case-insensitive. Ignored if --no-fold supplied. Available values: running, completed, failed, canceled, terminated, timedout, continueasnew. Can be passed multiple times.") + s.Command.Flags().BoolVar(&s.NoFold, "no-fold", false, "Disable folding. Fetch and display Child Workflows within the set depth.") + s.Command.Flags().IntVar(&s.Depth, "depth", -1, "Set depth for your Child Workflow fetches. Pass -1 to fetch child workflows at any depth.") + s.Command.Flags().IntVar(&s.Concurrency, "concurrency", 10, "Number of Workflow Histories to fetch at a time.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -2513,21 +2609,21 @@ func NewTemporalWorkflowUpdateCommand(cctx *CommandContext, parent *TemporalWork s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "update [flags]" - s.Command.Short = "Updates a running workflow synchronously." + s.Command.Short = "Synchronously run a Workflow update handler" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal workflow update\x1b[0m command is used to synchronously Update a\nWorkflowExecution by ID.\n\n\x1b[1mtemporal workflow update \\\n\t\t--workflow-id MyWorkflowId \\\n\t\t--name MyUpdate \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\x1b[0m\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Send a message to a Workflow Execution to invoke an update handler. An update\ncan change the state of a Workflow Execution and return a response:\n\n\x1b[1mtemporal workflow update \\\n --workflow-id YourWorkflowId \\\n --name YourUpdate \\\n --input '{\"Input\": \"As-JSON\"}'\x1b[0m" } else { - s.Command.Long = "The `temporal workflow update` command is used to synchronously Update a\nWorkflowExecution by ID.\n\n```\ntemporal workflow update \\\n\t\t--workflow-id MyWorkflowId \\\n\t\t--name MyUpdate \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\n```\n\nUse the options listed below to change the command's behavior." + s.Command.Long = "Send a message to a Workflow Execution to invoke an update handler. An update\ncan change the state of a Workflow Execution and return a response:\n\n```\ntemporal workflow update \\\n --workflow-id YourWorkflowId \\\n --name YourUpdate \\\n --input '{\"Input\": \"As-JSON\"}'\n```" } s.Command.Args = cobra.NoArgs s.PayloadInputOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().StringVar(&s.Name, "name", "", "Update Name. Required. Aliased as \"--type\".") + s.Command.Flags().StringVar(&s.Name, "name", "", "Handler method name. Required. Aliased as \"--type\".") _ = cobra.MarkFlagRequired(s.Command.Flags(), "name") - s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow Id. Required.") + s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow ID. Required.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "workflow-id") - s.Command.Flags().StringVar(&s.UpdateId, "update-id", "", "Update ID. If unset, default to a UUID.") - s.Command.Flags().StringVarP(&s.RunId, "run-id", "r", "", "Run Id. If unset, the currently running Workflow Execution receives the Update.") - s.Command.Flags().StringVar(&s.FirstExecutionRunId, "first-execution-run-id", "", "Send the Update to the last Workflow Execution in the chain that started with this Run Id.") + s.Command.Flags().StringVar(&s.UpdateId, "update-id", "", "Update ID. If unset, defaults to a UUID. Must be unique per Workflow Execution.") + s.Command.Flags().StringVarP(&s.RunId, "run-id", "r", "", "Run ID. If unset, updates the currently-running Workflow Execution.") + s.Command.Flags().StringVar(&s.FirstExecutionRunId, "first-execution-run-id", "", "Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID.") s.Command.Flags().SetNormalizeFunc(aliasNormalizer(map[string]string{ "type": "name", })) diff --git a/temporalcli/commandsmd/commands.md b/temporalcli/commandsmd/commands.md index c6b19ab0..c512411e 100644 --- a/temporalcli/commandsmd/commands.md +++ b/temporalcli/commandsmd/commands.md @@ -1,48 +1,230 @@ # Temporal CLI Commands -Commands for the Temporal CLI. +Commands for the Temporal CLI -### temporal: Temporal command-line interface and development server. +### temporal: Temporal command-line interface and development server + +The Temporal CLI manages, monitors, and debugs Temporal apps. It lets you run +a local Temporal Service, start Workflow Executions, pass messages to running +Workflows, inspect state, and more. + +* Start a local development service: + `temporal server start-dev` +* View help: pass `--help` to any command: + `temporal activity complete --help` -### temporal env set: Set environment properties. +### temporal env set: Set environment properties -`temporal env set --env environment -k property -v value` +Assign a value to a property key and store it to an environment: -Property names match CLI option names, for example '--address' and '--tls-cert-path': +``` +temporal env set \ + --env environment \ + --key property \ + --value value +``` -`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 (with `--env` or by setting the +`TEMPORAL_ENV` variable), this command sets properties in the "default" +environment. -If the environment is not specified, the `default` environment is used. +Storing keys with CLI option names lets the CLI automatically set those +options for you. This reduces effort and helps avoid typos when issuing +commands. #### Options -* `--active-cluster` (string) - Active cluster name. -* `--cluster` (string[]) - Cluster names. -* `--data` (string[]) - Namespace data in key=value format. Use JSON for values. -* `--description` (string) - Namespace description. -* `--email` (string) - Owner email. -* `--promote-global` (bool) - Promote local namespace to global namespace. -* `--history-archival-state` (string-enum) - History archival state. Options: disabled, enabled. -* `--history-uri` (string) - Optionally specify history archival URI (cannot be changed after first time archival is enabled). -* `--retention` (duration) - Length of time a closed Workflow is preserved before deletion. -* `--visibility-archival-state` (string-enum) - Visibility archival state. Options: disabled, enabled. -* `--visibility-uri` (string) - Optionally specify visibility archival URI (cannot be changed after first time archival is enabled). +* `--active-cluster` (string) - + Active Cluster (Service) name. +* `--cluster` (string[]) - + Cluster (Service) names. +* `--data` (string[]) - + Namespace data as `KEY=VALUE` pairs. + Keys must be identifiers, and values must be JSON values. + For example: 'YourKey={"your": "value"}'. + Can be passed multiple times. +* `--description` (string) - + Namespace description. +* `--email` (string) - + Owner email. +* `--promote-global` (bool) - + Enable multi-region data replication. +* `--history-archival-state` (string-enum) - + History archival state. + Options: disabled, enabled. +* `--history-uri` (string) - + Archive history to this `URI`. + Once enabled, can't be changed. +* `--retention` (duration) - + Length of time a closed Workflow is preserved before deletion +* `--visibility-archival-state` (string-enum) - + Visibility archival state. + Options: disabled, enabled. +* `--visibility-uri` (string) - + Archive visibility data to this `URI`. + Once enabled, can't be changed. + +### temporal operator search-attribute: Search Attribute operations + +Create, list, or remove Search Attributes fields stored in a Workflow +Execution's metadata: -### temporal operator search-attribute: Operations applying to Search Attributes +``` +temporal operator search-attribute create \ + --name YourAttributeName \ + --type Keyword +``` + +Supported types include: Text, Keyword, Int, Double, Bool, Datetime, and +KeywordList. -Search Attribute commands enable operations for the creation, listing, and removal of Search Attributes. +### temporal operator search-attribute create: Add custom Search Attributes -### temporal operator search-attribute create: Adds one or more custom Search Attributes +Add one or more custom Search Attributes: -`temporal operator search-attribute create` command adds one or more custom Search Attributes. +``` +temporal operator search-attribute create \ + --name YourAttributeName \ + --type Keyword +``` #### Options -* `--name` (string[]) - Search Attribute name. Required. -* `--type` (string[]) - Search Attribute type. Options: Text, Keyword, Int, Double, Bool, Datetime, KeywordList. Required. +* `--name` (string[]) - + Search Attribute name. + Required. +* `--type` (string[]) - + Search Attribute type. + Options: Text, Keyword, Int, Double, Bool, Datetime, KeywordList. + Required. -### temporal operator search-attribute list: Lists all Search Attributes that can be used in list Workflow Queries +### temporal operator search-attribute list: List Search Attributes -`temporal operator search-attribute list` displays a list of all Search Attributes. +Display a list of active Search Attributes that can be assigned or used with +Workflow Queries. You can manage this list and add attributes as needed: -### temporal operator search-attribute remove: Removes custom search attribute metadata only +``` +temporal operator search-attribute list +``` + +### temporal operator search-attribute remove: Remove custom Search Attributes -`temporal operator search-attribute remove` command removes custom Search Attribute metadata. +Remove custom Search Attributes from the options that can be assigned or used +with Workflow Queries. + +``` +temporal operator search-attribute remove \ + --name YourAttributeName +``` + +Remove attributes without confirmation: + +``` +temporal operator search-attribute remove \ + --name YourAttributeName \ + --yes +``` #### Options -* `--name` (string[]) - Search Attribute name. Required. -* `--yes`, `-y` (bool) - Confirm prompt to perform deletion. +* `--name` (string[]) - + Search Attribute name. + Required. +* `--yes`, `-y` (bool) - + Don't prompt to confirm removal. + +### temporal schedule: Perform operations on Schedules + +Create, use, and update Schedules that allow Workflow Executions to be created +at specified times: + +``` +temporal schedule [commands] [options] +``` -### temporal schedule: Perform operations on Schedules. +For example: -Schedule commands allow the user to create, use, and update Schedules. -Schedules allow starting Workflow Execution at regular times. +``` +temporal schedule describe \ + --schedule-id "YourScheduleId" +``` #### Options Includes options set for [client](#options-set-for-client). -### temporal schedule backfill: Backfills a past time range of actions. - - The `temporal schedule backfill` command runs the Actions that would have been run in a given time -interval, all at once. +### temporal schedule backfill: Backfill past actions - You can use backfill to fill in Workflow Runs from a time period when the Schedule was paused, from -before the Schedule was created, from the future, or to re-process an interval that was processed. +Batch-execute actions that would have run during a specified time interval. +Use this command to fill in Workflow runs from when a Schedule was paused, +before a Schedule was created, from the future, or to re-process a previously +executed interval. -Schedule backfills require a Schedule ID, along with the time in which to run the Schedule. You can -optionally override the overlap policy. It usually only makes sense to run backfills with either -`BufferAll` or `AllowAll` (other policies will only let one or two runs actually happen). +Backfills require a Schedule ID and the time period covered by the request. +It's best to use the `BufferAll` or `AllowAll` policies to avoid conflicts +and ensure no Workflow Executions are skipped. -Example: +For example: ``` - temporal schedule backfill \ - --schedule-id 'your-schedule-id' \ - --overlap-policy BufferAll \ - --start-time 2022-05-01T00:00:00Z \ - --end-time 2022-05-31T23:59:59Z + temporal schedule backfill \ + --schedule-id "YourScheduleId" \ + --start-time "2022-05-01T00:00:00Z" \ + --end-time "2022-05-31T23:59:59Z" \ + --overlap-policy BufferAll ``` +The policies include: + +* **AllowAll**: Allow unlimited concurrent Workflow Executions. This + significantly speeds up the backfilling process on systems that support + concurrency. You must ensure running Workflow Executions do not interfere + with each other. +* **BufferAll**: Buffer all incoming Workflow Executions while waiting for + the running Workflow Execution to complete. +* **Skip**: If a previous Workflow Execution is still running, discard new + Workflow Executions. +* **BufferOne**: Same as 'Skip' but buffer a single Workflow Execution to be + run after the previous Execution completes. Discard other Workflow + Executions. +* **CancelOther**: Cancel the running Workflow Execution and replace it with + the incoming new Workflow Execution. +* **TerminateOther**: Terminate the running Workflow Execution and replace + it with the incoming new Workflow Execution. + #### Options set for overlap policy: -* `--overlap-policy` (string-enum) - Overlap policy. Options: Skip, BufferOne, BufferAll, CancelOther, TerminateOther, AllowAll. Default: Skip. +* `--overlap-policy` (string-enum) - + Overlap policy. + Options: Skip, BufferOne, BufferAll, CancelOther, TerminateOther, AllowAll. + Default: Skip. #### Options set for schedule id: -* `--schedule-id`, `-s` (string) - Schedule id. Required. +* `--schedule-id`, `-s` (string) - + Schedule ID. + Required. #### Options -* `--end-time` (timestamp) - Backfill end time. Required. -* `--start-time` (timestamp) - Backfill start time. Required. +* `--end-time` (timestamp) - + Backfill end time. + Required. +* `--start-time` (timestamp) - + Backfill start time. + Required. -### temporal schedule create: Create a new Schedule. +### temporal schedule create: Create a new Schedule -The `temporal schedule create` command creates a new Schedule. +Create a new Schedule on the Temporal Service. A Schedule automatically starts +new Workflow Executions at the times you specify. -Example: +For example: ``` - temporal schedule create \ - --schedule-id 'your-schedule-id' \ - --calendar '{"dayOfWeek":"Fri","hour":"3","minute":"11"}' \ - --workflow-id 'your-base-workflow-id' \ - --task-queue 'your-task-queue' \ - --workflow-type 'YourWorkflowType' + temporal schedule create \ + --schedule-id "YourScheduleId" \ + --calendar '{"dayOfWeek":"Fri","hour":"3","minute":"30"}' \ + --workflow-id YourBaseWorkflowIdName \ + --task-queue YourTaskQueue \ + --workflow-type YourWorkflowType ``` -Any combination of `--calendar`, `--interval`, and `--cron` is supported. -Actions will be executed at any time specified in the Schedule. +Schedules support any combination of `--calendar`, `--interval`, and `--cron`: + +* Shorthand `--interval` strings. + For example: 45m (every 45 minutes) or 6h/5h (every 6 hours, at the top of + the 5th hour). +* JSON `--calendar`, as in the preceding example. +* Unix-style `--cron` strings and robfig declarations + (@daily/@weekly/@every X/etc). + For example, every Friday at 12:30 PM: `30 12 * * Fri`. #### Options set for schedule configuration: -* `--calendar` (string[]) - Calendar specification in JSON, e.g. `{"dayOfWeek":"Fri","hour":"17","minute":"5"}`. -* `--catchup-window` (duration) - Maximum allowed catch-up time if server is down. -* `--cron` (string[]) - Calendar spec in cron string format, e.g. `3 11 * * Fri`. -* `--end-time` (timestamp) - Overall schedule end time. -* `--interval` (string[]) - Interval duration, e.g. 90m, or 90m/13m to include phase offset. -* `--jitter` (duration) - Per-action jitter range. -* `--notes` (string) - Initial value of notes field. -* `--paused` (bool) - Initial value of paused state. -* `--pause-on-failure` (bool) - Pause schedule after any workflow failure. -* `--remaining-actions` (int) - Total number of actions allowed. Zero (default) means unlimited. -* `--start-time` (timestamp) - Overall schedule start time. -* `--time-zone` (string) - Time zone to interpret all calendar specs in (IANA name). -* `--schedule-search-attribute` (string[]) - Search Attribute for the _schedule_ in key=value format. Use valid JSON formats for value. -* `--schedule-memo` (string[]) - Memo for the _schedule_ in key=value format. Use valid JSON formats for value. +* `--calendar` (string[]) - + Calendar specification in JSON. + For example: `{"dayOfWeek":"Fri","hour":"17","minute":"5"}`. +* `--catchup-window` (duration) - + Maximum catch-up time for when the Service is unavailable. +* `--cron` (string[]) - + Calendar specification in cron string format. + For example: `"30 12 * * Fri"`. +* `--end-time` (timestamp) - + Schedule end time +* `--interval` (string[]) - + Interval duration. + For example, 90m, or 60m/15m to include phase offset. +* `--jitter` (duration) - + Max difference in time from the specification. + Vary the start time randomly within this amount. +* `--notes` (string) - + Initial notes field value. +* `--paused` (bool) - + Pause the Schedule immediately on creation. +* `--pause-on-failure` (bool) - + Pause schedule after Workflow failures. +* `--remaining-actions` (int) - + Total allowed actions. + Default is zero (unlimited). +* `--start-time` (timestamp) - + Schedule start time. +* `--time-zone` (string) - + Interpret calendar specs with the `TZ` time zone. + For a list of time zones, see: + https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. +* `--schedule-search-attribute` (string[]) - + Set schedule Search Attributes using `KEY="VALUE` pairs. + Keys must be identifiers, and values must be JSON values. + For example: 'YourKey={"your": "value"}'. + Can be passed multiple times. +* `--schedule-memo` (string[]) - + Set a schedule memo using `KEY=VALUE` pairs. + Keys must be identifiers, and values must be JSON values. + For example: 'YourKey={"your": "value"}'. + Can be passed multiple times. #### Options @@ -496,67 +1103,113 @@ Includes options set for [overlap-policy](#options-set-for-overlap-policy). Includes options set for [shared-workflow-start](#options-set-for-shared-workflow-start). Includes options set for [payload-input](#options-set-for-payload-input). -### temporal schedule delete: Deletes a Schedule. +### temporal schedule delete: Remove a Schedule -The `temporal schedule delete` command deletes a Schedule. -Deleting a Schedule does not affect any Workflows started by the Schedule. +Deletes a Schedule on the front end Service: -If you do also want to cancel or terminate Workflows started by a Schedule, consider using `temporal -workflow delete` with the `TemporalScheduledById` Search Attribute. +``` +temporal schedule delete \ + --schedule-id YourScheduleId +``` + +Removing a Schedule won't affect the Workflow Executions it started that are +still running. To cancel or terminate these Workflow Executions, use `temporal +workflow delete` with the `TemporalScheduledById` Search Attribute instead. #### Options Includes options set for [schedule-id](#options-set-for-schedule-id). -### temporal schedule describe: Get Schedule configuration and current state. +### temporal schedule describe: Display Schedule state -The `temporal schedule describe` command shows the current configuration of one Schedule, -including information about past, current, and future Workflow Runs. +Show a Schedule configuration, including information about past, current, and +future Workflow runs: + +``` +temporal schedule describe \ + --schedule-id YourScheduleId +``` #### Options Includes options set for [schedule-id](#options-set-for-schedule-id). -### temporal schedule list: Lists Schedules. +### temporal schedule list: Display hosted Schedules -The `temporal schedule list` command lists all Schedules in a namespace. +Lists the Schedules hosted by a Namespace: + +``` +temporal schedule list \ + --namespace YourNamespace +``` #### Options -* `--long`, `-l` (bool) - Include detailed information. -* `--really-long` (bool) - Include even more detailed information that's not really usable in table form. +* `--long`, `-l` (bool) - + Show detailed information +* `--really-long` (bool) - + Show extensive information in non-table form. + +### temporal schedule toggle: Pause or unpause a Schedule -### temporal schedule toggle: Pauses or unpauses a Schedule. +Pause or unpause a Schedule by passing a flag with your desired state: -The `temporal schedule toggle` command can pause and unpause a Schedule. +``` +temporal schedule toggle \ + --schedule-id "YourScheduleId" \ + --pause \ + --reason "YourReason" +``` -Toggling a Schedule takes a reason. The reason will be set as the `notes` field of the Schedule, -to help with operations communication. +and -Examples: +``` +temporal schedule toggle + --schedule-id "YourScheduleId" \ + --unpause \ + --reason "YourReason" +``` -* `temporal schedule toggle --schedule-id 'your-schedule-id' --pause --reason "paused because the database is down"` -* `temporal schedule toggle --schedule-id 'your-schedule-id' --unpause --reason "the database is back up"` +The `--reason` text updates the Schedule's `notes` field for operations +communication. It defaults to "(no reason provided)" if omitted. This field is +also visible on the Service Web UI. #### Options -* `--pause` (bool) - Pauses the schedule. -* `--reason` (string) - Reason for pausing/unpausing. Default: "(no reason provided)". -* `--unpause` (bool) - Pauses the schedule. +* `--pause` (bool) - + Pause the schedule. +* `--reason` (string) - + Reason for pausing or unpausing a Schedule. + Default: "(no reason provided)". +* `--unpause` (bool) - + Unpause the schedule. Includes options set for [schedule-id](#options-set-for-schedule-id). -### temporal schedule trigger: Triggers a schedule to take an action immediately. +### temporal schedule trigger: Immediately run a Schedule + +Trigger a Schedule to run immediately: + +``` +temporal schedule trigger \ + --schedule-id "YourScheduleId" +``` #### Options Includes options set for [schedule-id](#options-set-for-schedule-id). Includes options set for [overlap-policy](#options-set-for-overlap-policy). -### temporal schedule update: Updates a Schedule with a new definition. +### temporal schedule update: Update Schedule details -The temporal schedule update command updates an existing Schedule. It replaces the entire -configuration of the schedule, including spec, action, and policies. +Update an existing Schedule with new configuration details, including time +specifications, action, and policies: + +``` +temporal schedule update \ + --schedule-id "YourScheduleId" \ + --workflow-type "NewWorkflowType" +``` #### Options @@ -566,657 +1219,1336 @@ Includes options set for [overlap-policy](#options-set-for-overlap-policy). Includes options set for [shared-workflow-start](#options-set-for-shared-workflow-start). Includes options set for [payload-input](#options-set-for-payload-input). -### temporal server: Run Temporal Server. +### temporal server: Run Temporal Server -Start a development version of [Temporal Server](/concepts/what-is-the-temporal-server): +Run a development Temporal Server on your local system. View the Web UI for +the default configuration at http://localhost:8233: -`temporal server start-dev` +``` +temporal server start-dev +``` -### temporal server start-dev: Start Temporal development server. +Add persistence for Workflow Executions across runs: -Start [Temporal Server](/concepts/what-is-the-temporal-server) on `localhost:7233` with: +``` +temporal server start-dev \ + --db-filename path-to-your-local-persistent-store +``` -`temporal server start-dev` +Set the port from the front-end gRPC Service (7233 default): -View the UI at http://localhost:8233 +``` +temporal server start-dev \ + --port 7234 \ + --ui-port 8234 \ + --metrics-port 57271 +``` + +Use a custom port for the Web UI. The default is the gRPC port (7233 default) +plus 1000 (8233): + +``` +temporal server start-dev \ + --ui-port 3000 +``` + +### temporal server start-dev: Start Temporal development server + +Run a development Temporal Server on your local system. View the Web UI for +the default configuration at http://localhost:8233: + +``` +temporal server start-dev +``` -To persist Workflows across runs, use: +Add persistence for Workflow Executions across runs: -`temporal server start-dev --db-filename temporal.db` +``` +temporal server start-dev \ + --db-filename path-to-your-local-persistent-store +``` + +Set the port from the front-end gRPC Service (7233 default): + +``` +temporal server start-dev \ + --port 7000 +``` + +Use a custom port for the Web UI. The default is the gRPC port (7233 default) +plus 1000 (8233): + +``` +temporal server start-dev \ + --ui-port 3000 +``` #### Options -* `--db-filename`, `-f` (string) - File in which to persist Temporal state (by default, Workflows are lost when the - process dies). -* `--namespace`, `-n` (string[]) - Specify namespaces that should be pre-created (namespace "default" is always - created). -* `--port`, `-p` (int) - Port for the frontend gRPC service. Default: 7233. -* `--http-port` (int) - Port for the frontend HTTP API service. Default is off. -* `--metrics-port` (int) - Port for /metrics. Default is off. -* `--ui-port` (int) - Port for the Web UI. Default is --port + 1000. -* `--headless` (bool) - Disable the Web UI. -* `--ip` (string) - IP address to bind the frontend service to. Default: localhost. -* `--ui-ip` (string) - IP address to bind the Web UI to. Default is same as --ip. -* `--ui-asset-path` (string) - UI custom assets path. -* `--ui-codec-endpoint` (string) - UI remote codec HTTP endpoint. -* `--sqlite-pragma` (string[]) - Specify SQLite pragma statements in pragma=value format. -* `--dynamic-config-value` (string[]) - Dynamic config value, as KEY=JSON_VALUE (string values need quotes). -* `--log-config` (bool) - Log the server config being used to stderr. -* `--search-attribute` (string[]) - Search attributes to register, in key=type format. +* `--db-filename`, `-f` (string) - + Path to file for persistent Temporal state store. + By default, Workflow Executions are lost when the server process dies. +* `--namespace`, `-n` (string[]) - + Namespaces to be created at launch. + The "default" Namespace is always created automatically. +* `--port`, `-p` (int) - + Port for the frontend gRPC Service. + Default: 7233. +* `--http-port` (int) - + Port for the HTTP API service. + Default is off. +* `--metrics-port` (int) - + Port for '/metrics'. + Default is off. +* `--ui-port` (int) - + Port for the Web UI. + Default is '--port' value + 1000. +* `--headless` (bool) - + Disable the Web UI. +* `--ip` (string) - + IP address bound to the frontend Service. + Default: localhost. +* `--ui-ip` (string) - + IP address bound to the WebUI. + Default is same as '--ip' value. +* `--ui-asset-path` (string) - + UI custom assets path. +* `--ui-codec-endpoint` (string) - + UI remote codec HTTP endpoint. +* `--sqlite-pragma` (string[]) - + SQLite pragma statements in "PRAGMA=VALUE" format. +* `--dynamic-config-value` (string[]) - + Dynamic configuration value using `KEY=VALUE` pairs. + Keys must be identifiers, and values must be JSON values. + For example: 'YourKey="YourString"'. + Can be passed multiple times. +* `--log-config` (bool) - + Log the server config to stderr. +* `--search-attribute` (string[]) - + Search attributes to register using `KEY=VALUE` pairs. + Keys must be identifiers, and values must be JSON values. + For example: 'YourKey={"your": "value"}'. + Can be passed multiple times. + +### temporal task-queue: Manage Task Queues + +Inspect and update Task Queues, the queues that Workers poll for Workflow and +Activity tasks: -### temporal task-queue: Manage Task Queues. +``` +temporal task-queue [command] [command options] \ + --task-queue YourTaskQueue +``` + +For example: -Task Queue commands allow operations to be performed on [Task Queues](/concepts/what-is-a-task-queue). To run a Task -Queue command, run `temporal task-queue [command] [command options]`. +``` +temporal task-queue describe \ + --task-queue YourTaskQueue +``` #### Options Includes options set for [client](#options-set-for-client). -### temporal task-queue describe: Provides task reachability and pollers information for Workers on this Task Queue. +### temporal task-queue describe: Show active Workers -The `temporal task-queue describe` command provides task reachability information for the requested versions and all task types, -which can be used to safely retire Workers with old code versions, provided that they were assigned a Build ID. +Display a list of active Workers that have recently polled a Task Queue. The +Temporal Server records each poll request time. A `LastAccessTime` over one +minute may indicate the Worker is at capacity or has shut down. Temporal +Workers are removed if 5 minutes have passed since the last poll request. -The reachability states of a Build ID are: - - `Reachable`: the Build ID may be used by new workflows or activities -(based on versioning rules), or there are open workflows or backlogged activities assigned to it. - - `ClosedWorkflowsOnly`: the Build ID does not have open workflows, and is not reachable by new workflows, but MAY have closed workflows within the namespace retention period. - - `Unreachable`: indicates that this Build ID is not used for new executions, nor has been used by any existing execution within the retention period. +``` +temporal task-queue describe \ + --task-queue YourTaskQueue +``` -Task reachability is eventually consistent; there may be a delay until it converges to the most -accurate value but it is designed in a way to take the more conservative side until it converges. -For example, `Reachable` is more conservative than `ClosedWorkflowsOnly`. +This command provides poller information for a given Task Queue. +Workflow and Activity polling use separate Task Queues: -There is a non-trivial cost of computing task reachability, use the flag `--report-reachability` to enable it. +``` +temporal task-queue describe \ + --task-queue YourTaskQueue \ + --task-queue-type "activity"` +``` -This command also provides [poller](/application-development/worker-performance#poller-count) -information for a given [Task Queue](/concepts/what-is-a-task-queue). +Safely retire Workers assigned a Build ID by checking reachability across +all task types. Use the flag `--report-reachability`: -The [Server](/concepts/what-is-the-temporal-server) records the last time of each poll request. A `LastAccessTime` value -in excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the -Worker has shut down. [Workers](/concepts/what-is-a-worker) are removed if 5 minutes have passed since the last poll -request. +``` +temporal task-queue describe \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" \ + --report-reachability +``` -Information about the Task Queue can be returned to troubleshoot server issues. +Computing task reachability incurs a non-trivial computing cost. + +Build ID reachability states include: + +- `Reachable`: using the current versioning rules, the Build ID may be used + by new Workflow Executions or Activities OR there are currently open + Workflow or backlogged Activity tasks assigned to the queue. +- `ClosedWorkflowsOnly`: the Build ID does not have open Workflow Executions + and can't be reached by new Workflow Executions. It MAY have closed + Workflow Executions within the Namespace retention period. +- `Unreachable`: this Build ID is not used for new Workflow Executions and + isn't used by any existing Workflow Execution within the retention period. + +Task reachability is eventually consistent. You may experience a delay until +reachability converges to the most accurate value. This is designed to act +in the most conservative way until convergence. For example, `Reachable` is +more conservative than `ClosedWorkflowsOnly`. + +#### Options + +* `--task-queue`, `-t` (string) - + Task queue name. + Required. +* `--task-queue-type` (string[]) - + Task Queue type. + Options are: workflow, activity, nexus. +* `--select-build-id` (string[]) - + Filter the Task Queue based on Build ID. +* `--select-unversioned` (bool) - + Include the unversioned queue. +* `--select-all-active` (bool) - + Include all active versions. + A version is active if it had new tasks or polls recently. +* `--report-reachability` (bool) - + Display task reachability information. +* `--legacy-mode` (bool) - + Enable a legacy mode for servers that do not support rules-based + worker versioning. + This mode only provides pollers info. +* `--task-queue-type-legacy` (string-enum) - Task Queue type (legacy mode only). + Options: workflow, activity. + Default: workflow. +* `--partitions-legacy` (int) - + Query partitions 1 through `N`. + Experimental/Temporary feature. + Legacy mode only. + Default: 1. + +### temporal task-queue get-build-id-reachability: Show Build ID availability (Deprecated) + ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ + +Show if a given Build ID can be used for new, existing, or closed Workflows +in Namespaces that support Worker versioning: -Use the options listed below to modify what this command returns. +``` +temporal task-queue get-build-id-reachability \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" +``` -Note that without a `--select-*` option the result for the default Build ID will be returned. -The default Build ID is the one mentioned in the first unconditional Assignment Rule. -If there is no default Build ID, the result for the unversioned queue will be returned. +You can specify the `--build-id` and `--task-queue` flags multiple times. If +`--task-queue` is omitted, the command checks Build ID reachability against +all Task Queues. #### Options -* `--task-queue`, `-t` (string) - Task queue name. Required. -* `--task-queue-type` (string[]) - Task queue types considered. If not specified, all types are reported. The current valid queue types are workflow, activity, or nexus. -* `--select-build-id` (string[]) - Task queue filter based on Build ID. -* `--select-unversioned` (bool) - Include the unversioned queue. -* `--select-all-active` (bool) - Include all active versions. A version is active if it had new tasks or polls recently. -* `--report-reachability` (bool) - Display task reachability information. -* `--legacy-mode` (bool) - Enable a legacy mode for servers that do not support rules-based worker versioning. This mode only provides pollers info. -* `--task-queue-type-legacy` (string-enum) - Task Queue type (legacy mode only). Options: workflow, activity. Default: workflow. -* `--partitions-legacy` (int) - Query for all partitions up to this number (experimental+temporary feature) (legacy mode only). Default: 1. +* `--build-id` (string[]) - + One or more Build ID strings. + Can be passed multiple times. +* `--reachability-type` (string-enum) - + Reachability filter. + `open`: reachable by one or more open workflows. + `closed`: reachable by one or more closed workflows. + `existing`: reachable by either. + New Workflow Executions reachable by a Build ID are always reported. + Options: open, closed, existing. + Default: existing. +* `--task-queue`, `-t` (string[]) - + Search only the specified task queue(s). + Can be passed multiple times. + +### temporal task-queue get-build-ids: Fetch Build ID versions (Deprecated) + ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ -### temporal task-queue get-build-id-reachability: Retrieves information about the reachability of Build IDs on one or more Task Queues (Deprecated). +Fetch sets of compatible Build IDs for specified Task Queues and display their +information: -This command can tell you whether or not Build IDs may be used for new, existing, or closed workflows. Both the '--build-id' and '--task-queue' flags may be specified multiple times. If you do not provide a task queue, reachability for the provided Build IDs will be checked against all task queues. +``` +temporal task-queue get-build-ids \ + --task-queue YourTaskQueue +``` + +This command is limited to Namespaces that support Worker versioning. #### Options -* `--build-id` (string[]) - Which Build ID to get reachability information for. May be specified multiple times. -* `--reachability-type` (string-enum) - Specify how you'd like to filter the reachability of Build IDs. Valid choices are `open` (reachable by one or more open workflows), `closed` (reachable by one or more closed workflows), or `existing` (reachable by either). If a Build ID is reachable by new workflows, that is always reported. Options: open, closed, existing. Default: existing. -* `--task-queue`, `-t` (string[]) - Which Task Queue(s) to constrain the reachability search to. May be specified multiple times. +* `--task-queue`, `-t` (string) - + Task queue name. + Required. +* `--max-sets` (int) - + Max return count. + Use 1 for default major version. + Use 0 for all sets. + Default: 0. -### temporal task-queue get-build-ids: Fetch the sets of worker Build ID versions on the Task Queue (Deprecated). +### temporal task-queue list-partition: List Task Queue partitions -Fetch the sets of compatible build IDs associated with a Task Queue and associated information. +Display a Task Queue's partition list with assigned matching nodes: + +``` +temporal task-queue list-partition \ + --task-queue YourTaskQueue +``` #### Options -* `--task-queue`, `-t` (string) - Task queue name. Required. -* `--max-sets` (int) - Limits how many compatible sets will be returned. Specify 1 to only return the current default major version set. 0 returns all sets. (default: 0). Default: 0. +* `--task-queue`, `-t` (string) - + Task Queue name. + Required. -### temporal task-queue list-partition: Lists the Task Queue's partitions and the matching nodes they are assigned to. +### temporal task-queue update-build-ids: Manage Build IDs (Deprecated) -The temporal task-queue list-partition command displays the partitions of a Task Queue, along with the matching node they are assigned to. ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ -#### Options +Add or change a Task Queue's compatible Build IDs for Namespaces using Worker +versioning: + +``` +temporal task-queue update-build-ids [subcommands] [options] \ + --task-queue YourTaskQueue +``` -* `--task-queue`, `-t` (string) - Task queue name. Required. +### temporal task-queue update-build-ids add-new-compatible: Add compatible Build ID -### temporal task-queue update-build-ids: Operations to update the sets of worker Build ID versions on the Task Queue (Deprecated). +Add a compatible Build ID to a Task Queue's existing version set. Provide an +existing Build ID and a new Build ID: -Provides various commands for adding or changing the sets of compatible build IDs associated with a Task Queue. See the help of each sub-command for more. +``` +temporal task-queue update-build-ids add-new-compatible \ + --task-queue YourTaskQueue \ + --existing-compatible-build-id "YourExistingBuildId" \ + --build-id "YourNewBuildId" +``` -### temporal task-queue update-build-ids add-new-compatible: Add a new build ID compatible with an existing ID to the Task Queue version sets. +The new ID is stored in the set containing the existing ID and becomes the new +default for that set. -The new build ID will become the default for the set containing the existing ID. See per-flag help for more. +This command is limited to Namespaces that support Worker versioning. #### Options -* `--build-id` (string) - The new build id to be added. Required. -* `--task-queue`, `-t` (string) - Name of the Task Queue. Required. -* `--existing-compatible-build-id` (string) - A build id which must already exist in the version sets known by the task queue. The new id will be stored in the set containing this id, marking it as compatible with the versions within. Required. -* `--set-as-default` (bool) - When set, establishes the compatible set being targeted as the overall default for the queue. If a different set was the current default, the targeted set will replace it as the new default. Defaults to false. +* `--build-id` (string) - + Build ID to be added. + Required. +* `--task-queue`, `-t` (string) - + Task Queue name. + Required. +* `--existing-compatible-build-id` (string) - + Pre-existing Build ID in this Task Queue. + Required. +* `--set-as-default` (bool) - + Set the expanded Build ID set as the Task Queue default. + Defaults to false. + +### temporal task-queue update-build-ids add-new-default: Set new default Build ID set (Deprecated) + ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ + +Create a new Task Queue Build ID set, add a Build ID to it, and make it the +overall Task Queue default. The new set will be incompatible with previous +sets and versions. -### temporal task-queue update-build-ids add-new-default: Add a new default (incompatible) build ID to the Task Queue version sets. +``` +temporal task-queue update-build-ids add-new-default \ + --task-queue YourTaskQueue \ + --build-id "YourNewBuildId" +``` -Creates a new build id set which will become the new overall default for the queue with the provided build id as its only member. This new set is incompatible with all previous sets/versions. ++------------------------------------------------------------------------+ +| NOTICE: This command is limited to Namespaces that support Worker | +| versioning. Worker versioning is experimental. Versioning commands are | +| subject to change. | ++------------------------------------------------------------------------+ #### Options -* `--build-id` (string) - The new build id to be added. Required. -* `--task-queue`, `-t` (string) - Name of the Task Queue. Required. +* `--build-id` (string) - + Build ID to be added. + Required. +* `--task-queue`, `-t` (string) - + Task Queue name. + Required. + +### temporal task-queue update-build-ids promote-id-in-set: Set Build ID as set default (Deprecated) + ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ + +Establish an existing Build ID as the default in its Task Queue set. New tasks +compatible with this set will now be dispatched to this ID: -### temporal task-queue update-build-ids promote-id-in-set: Promote an existing build ID to become the default for its containing set. +``` +temporal task-queue update-build-ids promote-id-in-set \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" +``` -New tasks compatible with the set will be dispatched to the default id. ++------------------------------------------------------------------------+ +| NOTICE: This command is limited to Namespaces that support Worker | +| versioning. Worker versioning is experimental. Versioning commands are | +| subject to change. | ++------------------------------------------------------------------------+ #### Options -* `--build-id` (string) - An existing build id which will be promoted to be the default inside its containing set. Required. -* `--task-queue`, `-t` (string) - Name of the Task Queue. Required. +* `--build-id` (string) - + Build ID to set as default. + Required. +* `--task-queue`, `-t` (string) - + Task Queue name. + Required. + +### temporal task-queue update-build-ids promote-set: Promote Build ID set (Deprecated) + ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ + +Promote a Build ID set to be the default on a Task Queue. Identify the set by +providing a Build ID within it. If the set is already the default, this +command has no effect: -### temporal task-queue update-build-ids promote-set: Promote an existing build ID set to become the default for the Task Queue. +``` +temporal task-queue update-build-ids promote-set \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" +``` -If the set is already the default, this command has no effect. ++------------------------------------------------------------------------+ +| NOTICE: This command is limited to Namespaces that support Worker | +| versioning. Worker versioning is experimental. Versioning commands are | +| subject to change. | ++------------------------------------------------------------------------+ #### Options -* `--build-id` (string) - An existing build id whose containing set will be promoted. Required. -* `--task-queue`, `-t` (string) - Name of the Task Queue. Required. +* `--build-id` (string) - + Build ID within the promoted set. + Required. +* `--task-queue`, `-t` (string) - + Task Queue name. + Required. + +### temporal task-queue versioning: manage Task Queue Build ID handling (Experimental) + ++---------------------------------------------------------------------+ +| CAUTION: Worker versioning is experimental. Versioning commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Provides commands to add, list, remove, or replace Worker Build ID assignment +and redirect rules associated with Task Queues: -### temporal task-queue versioning: Updates or retrieves the worker Build ID assignment and redirect rules on the Task Queue. +``` +temporal task-queue versioning [subcommands] [options] \ + --task-queue YourTaskQueue +``` + +Task Queues support the following versioning rules and policies: -Provides various commands for adding, listing, removing, or replacing worker Build ID assignment and redirect rules associated with a Task Queue. See the help of each sub-command for more. +- Assignment Rules: manage how new executions are assigned to run on specific + Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules, + which are evaluated from first to last. Assignment Rules also allow for + gradual rollout of new Build IDs by setting ramp percentage. +- Redirect Rules: automatically assign work for a source Build ID to a target + Build ID. You may add at most one redirect rule for each source Build ID. + Redirect rules require that a target Build ID is fully compatible with + the source Build ID. #### Options -* `--task-queue`, `-t` (string) - Task queue name. Required. +* `--task-queue`, `-t` (string) - + Task queue name. + Required. + +### temporal task-queue versioning add-redirect-rule: Add Task Queue redirect rules (Experimental) + +Add a new redirect rule for a given Task Queue. You may add at most one +redirect rule for each distinct source build ID: -### temporal task-queue versioning add-redirect-rule: Adds the rule to the list of redirect rules for this Task Queue. +``` +temporal task-queue versioning add-redirect-rule \ + --task-queue YourTaskQueue \ + --source-build-id "YourSourceBuildID" \ + --target-build-id "YourTargetBuildID" +``` -Adds a new redirect rule for this Task Queue. There can be at most one redirect rule for each distinct source build ID. ++---------------------------------------------------------------------+ +| CAUTION: Worker versioning is experimental. Versioning commands are | +| subject to change. | ++---------------------------------------------------------------------+ #### Options -* `--source-build-id` (string) - The source build ID for this redirect rule. Required. -* `--target-build-id` (string) - The target build ID for this redirect rule. Required. -* `--yes`, `-y` (bool) - Skip confirmation. +* `--source-build-id` (string) - + Source build ID. + Required. +* `--target-build-id` (string) - + Target build ID. + Required. +* `--yes`, `-y` (bool) - + Don't prompt to confirm. + +### temporal task-queue versioning commit-build-id: Complete Build ID rollout (Experimental) + +Complete a Build ID's rollout and clean up unnecessary rules that might have +been created during a gradual rollout: + +``` +temporal task-queue versioning commit-build-id \ + --task-queue YourTaskQueue + --build-id "YourBuildId" +``` -### temporal task-queue versioning commit-build-id: Completes the rollout of a Build ID for this Task Queue. +This command automatically applies the following atomic changes: -Completes the rollout of a BuildID and cleanup unnecessary rules possibly -created during a gradual rollout. Specifically, this command will make the -following changes atomically: - 1. Adds an unconditional assignment rule for the target Build ID at the end of the list. - 2. Removes all previously added assignment rules to the given target Build ID. - 3. Removes any unconditional assignment rules for other Build IDs. +- Adds an unconditional assignment rule for the target Build ID at the + end of the list. +- Removes all previously added assignment rules to the given target + Build ID. +- Removes any unconditional assignment rules for other Build IDs. -To prevent committing invalid Build IDs, we reject the request if no pollers -have been seen recently for this Build ID. Use the `force` option to disable this validation. +Rejects requests when there have been no recent pollers for this Build ID. +This prevents committing invalid Build IDs. Use the `--force` option to +override this validation. ++---------------------------------------------------------------------+ +| CAUTION: Worker versioning is experimental. Versioning commands are | +| subject to change. | ++---------------------------------------------------------------------+ #### Options -* `--build-id` (string) - The target build ID to be committed. Required. -* `--force` (bool) - Bypass the validation that pollers have been recently seen for this build ID. -* `--yes`, `-y` (bool) - Skip confirmation. +* `--build-id` (string) - + Target build ID. + Required. +* `--force` (bool) - + Bypass recent-poller validation. +* `--yes`, `-y` (bool) - + Don't prompt to confirm. + +### temporal task-queue versioning delete-assignment-rule: Removes a Task Queue assignment rule (Experimental) -### temporal task-queue versioning delete-assignment-rule: Deletes the rule at a given index in the list of assignment rules for this Task Queue. +Deletes a rule identified by its index in the Task Queue's list of assignment +rules. -Deletes an assignment rule for this Task Queue. By default presence of one -unconditional rule, i.e., no hint filter or percentage, is enforced, otherwise -the delete operation will be rejected. Set `force` to true to bypass this -validation. +``` +temporal task-queue versioning delete-assignment-rule \ + --task-queue YourTaskQueue \ + --rule-index YourIntegerRuleIndex +``` + +By default, the Task Queue must retain one unconditional rule, such as "no +hint filter" or "percentage". Otherwise, the delete operation is rejected. +Use the `--force` option to override this validation. + ++---------------------------------------------------------------------+ +| CAUTION: Worker versioning is experimental. Versioning commands are | +| subject to change. | ++---------------------------------------------------------------------+ #### Options -* `--rule-index`, `-i` (int) - Position of the assignment rule to be replaced. Required. -* `--yes`, `-y` (bool) - Skip confirmation. -* `--force` (bool) - Bypass the validation that one unconditional rule remains. +* `--rule-index`, `-i` (int) - + Position of the assignment rule to be replaced. + Requests for invalid indices will fail. + Required. +* `--force` (bool) - + Bypass one-unconditional-rule validation. +* `--yes`, `-y` (bool) - + Don't prompt to confirm. + +### temporal task-queue versioning delete-redirect-rule: Removes Build-ID routing rule (Experimental) -### temporal task-queue versioning delete-redirect-rule: Deletes the rule with the given build ID for this Task Queue. +Deletes the routing rule for the given source Build ID. + +``` +temporal task-queue versioning delete-redirect-rule \ + --task-queue YourTaskQueue \ + --source-build-id "YourBuildId" +``` -Deletes the routing rule with the given source Build ID. ++---------------------------------------------------------------------+ +| CAUTION: Worker versioning is experimental. Versioning commands are | +| subject to change. | ++---------------------------------------------------------------------+ #### Options -* `--source-build-id` (string) - The source build ID for this redirect rule. Required. -* `--yes`, `-y` (bool) - Skip confirmation. +* `--source-build-id` (string) - + Source Build ID. + Required. +* `--yes`, `-y` (bool) - + Don't prompt to confirm. + +### temporal task-queue versioning get-rules: Fetch Worker Build ID assignments and redirect rules (Experimental) + +Retrieve all the Worker Build ID assignments and redirect rules associated +with a Task Queue. + +``` +temporal task-queue versioning get-rules \ + --task-queue YourTaskQueue +``` + +Task Queues support the following versioning rules: + +- Assignment Rules: manage how new executions are assigned to run on specific + Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules, + which are evaluated from first to last. Assignment Rules also allow for + gradual rollout of new Build IDs by setting ramp percentage. +- Redirect Rules: automatically assign work for a source Build ID to a target + Build ID. You may add at most one redirect rule for each source Build ID. + Redirect rules require that a target Build ID is fully compatible with + the source Build ID. + ++---------------------------------------------------------------------+ +| CAUTION: Worker versioning is experimental. Versioning commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +### temporal task-queue versioning insert-assignment-rule: Add an assignment rule at a index (Experimental) -### temporal task-queue versioning get-rules: Retrieves the worker Build ID assignment and redirect rules on the Task Queue. +Inserts a new assignment rule for this Task Queue. Rules are evaluated in +order, starting from index 0. The first applicable rule is applied, and the +rest ignored: -Fetch the worker build ID assignment and redirect rules associated with a Task Queue. +``` +temporal task-queue versioning insert-assignment-rule \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" +``` -### temporal task-queue versioning insert-assignment-rule: Inserts the rule to the list of assignment rules for this Task Queue. +If you do not specify a `--rule-index`, this command inserts at index 0. -Inserts a new assignment rule for this Task Queue. The rules are evaluated in order, starting from index 0. The first applicable rule will be applied and the rest will be ignored. ++---------------------------------------------------------------------+ +| CAUTION: Worker versioning is experimental. Versioning commands are | +| subject to change. | ++---------------------------------------------------------------------+ #### Options -* `--build-id` (string) - The target build ID for this assignment rule. Required. -* `--rule-index`, `-i` (int) - Insertion position in the assignment rule list. An index 0 means insert at the beginning of the list. If the given index is larger than the list size, the rule will be appended at the end of the list. Default: 0. -* `--percentage` (int) - Percentage of traffic sent to the target build ID. Default: 100. -* `--yes`, `-y` (bool) - Skip confirmation. +* `--build-id` (string) - + Target Build ID. + Required. +* `--rule-index`, `-i` (int) - + Insertion position. + Ranges from 0 (insert at start) to count (append). + Any number greater than the count is treated as "append". + Default: 0. +* `--percentage` (int) - + Traffic percent to send to target Build ID. + Default: 100. +* `--yes`, `-y` (bool) - + Don't prompt to confirm. + +### temporal task-queue versioning replace-assignment-rule: Update assignment rule at index (Experimental) + +Change an assignment rule for this Task Queue. By default, this enforces one +unconditional rule (no hint filter or percentage). Otherwise, the operation +will be rejected. Set `force` to true to bypass this validation. + +``` +temporal task-queue versioning replace-assignment-rule + --task-queue YourTaskQueue \ + --rule-index AnIntegerIndex \ + --build-id "YourBuildId" +``` + +To assign multiple assignment rules to a single Build ID, use +'insert-assignment-rule'. + +To update the percent: + +``` +temporal task-queue versioning replace-assignment-rule + --task-queue YourTaskQueue \ + --rule-index AnIntegerIndex \ + --build-id "YourBuildId" \ + --percentage AnIntegerPercent +``` -### temporal task-queue versioning replace-assignment-rule: Replaces the rule at a given index in the list of assignment rules for this Task Queue. +Percent may vary between 0 and 100 (default). -Replaces an assignment rule for this Task Queue. By default presence of one -unconditional rule, i.e., no hint filter or percentage, is enforced, otherwise -the delete operation will be rejected. Set `force` to true to bypass this -validation. ++---------------------------------------------------------------------+ +| CAUTION: Worker versioning is experimental. Versioning commands are | +| subject to change. | ++---------------------------------------------------------------------+ #### Options -* `--build-id` (string) - The target build ID for this assignment rule. Required. -* `--rule-index`, `-i` (int) - Position of the assignment rule to be replaced. Required. -* `--percentage` (int) - Percentage of traffic sent to the target build ID. Default: 100. -* `--yes`, `-y` (bool) - Skip confirmation. -* `--force` (bool) - Bypass the validation that one unconditional rule remains. +* `--build-id` (string) - + Target Build ID. + Required. +* `--rule-index`, `-i` (int) - + Position of the assignment rule to be replaced. + Requests for invalid indices will fail. + Required. +* `--percentage` (int) - + Divert percent of traffic to target Build ID. + Default: 100. +* `--yes`, `-y` (bool) - + Don't prompt to confirm. +* `--force` (bool) - + Bypass the validation that one unconditional rule remains. + +### temporal task-queue versioning replace-redirect-rule: Change the target for a Build ID's redirect (Experimental) -### temporal task-queue versioning replace-redirect-rule: Replaces the redirect rule with the given source build ID for this Task Queue. +Updates a Build ID's redirect rule on a Task Queue by replacing its target +Build ID. + +``` +temporal task-queue versioning replace-redirect-rule + --task-queue YourTaskQueue \ + --source-build-id YourSourceBuildId \ + --target-build-id YourNewTargetBuildId +``` -Replaces the redirect rule with the given source build ID for this Task Queue. ++---------------------------------------------------------------------+ +| CAUTION: Worker versioning is experimental. Versioning commands are | +| subject to change. | ++---------------------------------------------------------------------+ #### Options -* `--source-build-id` (string) - The source build ID for this redirect rule. Required. -* `--target-build-id` (string) - The target build ID for this redirect rule. Required. -* `--yes`, `-y` (bool) - Skip confirmation. +* `--source-build-id` (string) - + Source Build ID. + Required. +* `--target-build-id` (string) - + Target Build ID. + Required. +* `--yes`, `-y` (bool) - + Don't prompt to confirm. -### temporal workflow: Start, list, and operate on Workflows. +### temporal workflow: Start, list, and operate on Workflows -[Workflow](/concepts/what-is-a-workflow) commands perform operations on [Workflow Executions](/concepts/what-is-a-workflow-execution). +Workflow commands perform operations on Workflow Executions: -Workflow commands use this syntax: `temporal workflow COMMAND [ARGS]`. +``` +temporal workflow [command] [options] +``` -#### Options set for client: +For example: -* `--address` (string) - Temporal server address. Default: 127.0.0.1:7233. Env: TEMPORAL_ADDRESS. -* `--namespace`, `-n` (string) - Temporal server namespace. Default: default. Env: TEMPORAL_NAMESPACE. -* `--api-key` (string) - Sets the API key on requests. Env: TEMPORAL_API_KEY. -* `--grpc-meta` (string[]) - HTTP headers to send with requests (formatted as key=value). -* `--tls` (bool) - Enable TLS encryption without additional options such as mTLS or client certificates. Env: - TEMPORAL_TLS. -* `--tls-cert-path` (string) - Path to x509 certificate. Env: TEMPORAL_TLS_CERT. -* `--tls-key-path` (string) - Path to private certificate key. Env: TEMPORAL_TLS_KEY. -* `--tls-ca-path` (string) - Path to server CA certificate. Env: TEMPORAL_TLS_CA. -* `--tls-cert-data` (string) - Data for x509 certificate. Exclusive with -path variant. Env: TEMPORAL_TLS_CERT_DATA. -* `--tls-key-data` (string) - Data for private certificate key. Exclusive with -path variant. Env: TEMPORAL_TLS_KEY_DATA. -* `--tls-ca-data` (string) - Data for server CA certificate. Exclusive with -path variant. Env: TEMPORAL_TLS_CA_DATA. -* `--tls-disable-host-verification` (bool) - Disables TLS host-name verification. Env: - TEMPORAL_TLS_DISABLE_HOST_VERIFICATION. -* `--tls-server-name` (string) - Overrides target TLS server name. Env: TEMPORAL_TLS_SERVER_NAME. -* `--codec-endpoint` (string) - Endpoint for a remote Codec Server. Env: TEMPORAL_CODEC_ENDPOINT. -* `--codec-auth` (string) - Sets the authorization header on requests to the Codec Server. Env: TEMPORAL_CODEC_AUTH. +``` +temporal workflow list +``` -### temporal workflow cancel: Cancel a Workflow Execution. +#### Options set for client: -The `temporal workflow cancel` command is used to cancel a [Workflow Execution](/concepts/what-is-a-workflow-execution). -Canceling a running Workflow Execution records a `WorkflowExecutionCancelRequested` event in the Event History. A new -Command Task will be scheduled, and the Workflow Execution will perform cleanup work. +* `--address` (string) - + Temporal Service gRPC endpoint. + Default: 127.0.0.1:7233. + Env: TEMPORAL_ADDRESS. +* `--namespace`, `-n` (string) - + Temporal Service Namespace. + Default: default. + Env: TEMPORAL_NAMESPACE. +* `--api-key` (string) - + API key for request. + Env: TEMPORAL_API_KEY. +* `--grpc-meta` (string[]) - + HTTP headers for requests. + Format as a `KEY=VALUE` pair. + May be passed multiple times to set multiple headers. +* `--tls` (bool) - + Enable base TLS encryption. + Does not have additional options like mTLS or client certs. + Env: TEMPORAL_TLS. +* `--tls-cert-path` (string) - + Path to x509 certificate. + Can't be used with --tls-cert-data. + Env: TEMPORAL_TLS_CERT. +* `--tls-cert-data` (string) - + Data for x509 certificate. + Can't be used with --tls-cert-path. + Env: TEMPORAL_TLS_CERT_DATA. +* `--tls-key-path` (string) - + Path to x509 private key. + Can't be used with --tls-key-data. + Env: TEMPORAL_TLS_KEY. +* `--tls-key-data` (string) - + Private certificate key data. + Can't be used with --tls-key-path. + Env: TEMPORAL_TLS_KEY_DATA. +* `--tls-ca-path` (string) - + Path to server CA certificate. + Can't be used with --tls-ca-data. + Env: TEMPORAL_TLS_CA. +* `--tls-ca-data` (string) - + Data for server CA certificate. + Can't be used with --tls-ca-path. + Env: TEMPORAL_TLS_CA_DATA. +* `--tls-disable-host-verification` (bool) - + Disable TLS host-name verification. + Env: TEMPORAL_TLS_DISABLE_HOST_VERIFICATION. +* `--tls-server-name` (string) - + Override target TLS server name. + Env: TEMPORAL_TLS_SERVER_NAME. +* `--codec-endpoint` (string) - + Remote Codec Server endpoint. + Env: TEMPORAL_CODEC_ENDPOINT. +* `--codec-auth` (string) - + Authorization header for Codec Server requests. + Env: TEMPORAL_CODEC_AUTH. + +### temporal workflow cancel: Send cancellation to Workflow Execution + +Canceling a running Workflow Execution records a +`WorkflowExecutionCancelRequested` event in the Event History. The Service +schedules a new Command Task, and the Workflow Execution performs any cleanup +work supported by its implementation. + +Use the Workflow ID to cancel an Execution: -Executions may be cancelled by [ID](/concepts/what-is-a-workflow-id): ``` -temporal workflow cancel --workflow-id MyWorkflowId +temporal workflow cancel \ + --workflow-id YourWorkflowId ``` -...or in bulk via a visibility query [list filter](/concepts/what-is-a-list-filter): +A visibility Query lets you send bulk cancellations to Workflow Executions +matching the results: + ``` -temporal workflow cancel --query=MyQuery +temporal workflow cancel \ + --query YourQuery ``` -Use the options listed below to change the behavior of this command. +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. #### Options -Includes options set for [single workflow or batch](#options-set-single-workflow-or-batch) +Includes options set for [single workflow or batch](#options-set-single-workflow-or-batch). -### temporal workflow count: Count Workflow Executions. +### temporal workflow count: Number of Workflow Executions -The `temporal workflow count` command returns a count of [Workflow Executions](/concepts/what-is-a-workflow-execution). +Show a count of Workflow Executions, regardless of execution state (running, +terminated, etc). Use `--query` to select a subset of Workflow Executions: + +``` +temporal workflow count \ + --query YourQuery +``` -Use the options listed below to change the command's behavior. +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. #### Options -* `--query`, `-q` (string) - Filter results using a SQL-like query. +* `--query`, `-q` (string) - + Content for an SQL-like `QUERY` List Filter. -### temporal workflow delete: Deletes a Workflow Execution. +### temporal workflow delete: Remove Workflow Execution -The `temporal workflow delete` command is used to delete a specific [Workflow Execution](/concepts/what-is-a-workflow-execution). -This asynchronously deletes a workflow's [Event History](/concepts/what-is-an-event-history). -If the [Workflow Execution](/concepts/what-is-a-workflow-execution) is Running, it will be terminated before deletion. +Delete a Workflow Executions and its Event History: ``` temporal workflow delete \ - --workflow-id MyWorkflowId \ + --workflow-id YourWorkflowId ``` -Use the options listed below to change the command's behavior. - -#### Options +The removal executes asynchronously. If the Execution is Running, the Service +terminates it before deletion. -Includes options set for [single workflow or batch](#options-set-single-workflow-or-batch) +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. -### temporal workflow describe: Show information about a Workflow Execution. +#### Options -The `temporal workflow describe` command shows information about a given -[Workflow Execution](/concepts/what-is-a-workflow-execution). +Includes options set for [single workflow or batch](#options-set-single-workflow-or-batch). -This information can be used to locate Workflow Executions that weren't able to run successfully. +### temporal workflow describe: Show Workflow Execution info -`temporal workflow describe --workflow-id=meaningful-business-id` +Display information about a specific Workflow Execution: -Output can be shown as printed ('raw') or formatted to only show the Workflow Execution's auto-reset points. +``` +temporal workflow describe \ + --workflow-id YourWorkflowId +``` -`temporal workflow describe --workflow-id=meaningful-business-id --raw=true --reset-points=true` +Show the Workflow Execution's auto-reset points: -Use the command options below to change the information returned by this command. +``` +temporal workflow describe \ + --workflow-id YourWorkflowId \ + --reset-points true +``` -#### Options set for workflow reference +#### Options set for workflow reference: -* `--workflow-id`, `-w` (string) - Workflow Id. Required. -* `--run-id`, `-r` (string) - Run Id. +* `--workflow-id`, `-w` (string) - + Workflow ID. + Required. +* `--run-id`, `-r` (string) - + Run ID. #### Options -* `--reset-points` (bool) - Only show auto-reset points. -* `--raw` (bool) - Print properties without changing their format. +* `--reset-points` (bool) - + Show auto-reset points only. +* `--raw` (bool) - + Print properties without changing their format. + Defaults to true. -### temporal workflow execute: Start a new Workflow Execution and prints its progress. +### temporal workflow execute: Start new Workflow Execution -The `temporal workflow execute` command starts a new [Workflow Execution](/concepts/what-is-a-workflow-execution) and -prints its progress. The command completes when the Workflow Execution completes. - -Single quotes('') are used to wrap input as JSON. +Establish a new Workflow Execution and direct its progress to stdout. The +command blocks and returns when the Workflow Execution completes. If your +Workflow requires input, pass valid JSON: ``` temporal workflow execute - --workflow-id meaningful-business-id \ - --type MyWorkflow \ - --task-queue MyTaskQueue \ - --input '{"Input": "As-JSON"}' + --workflow-id YourWorkflowId \ + --type YourWorkflow \ + --task-queue YourTaskQueue \ + --input '{"Input": "As-JSON"}' ``` +Use `--event-details` to relay updates to the command-line output in JSON +format. When using JSON output (`--output json`), this includes the entire +"history" JSON key for the run. + #### Options -* `--detailed` (bool) - If set when using text output, display events as sections with detail instead of simple table. - If set when using JSON output, this will include the entire "history" JSON key of the started run (does not follow - runs). +* `--detailed` (bool) - + Display events as sections instead of table. + Does not apply to JSON output. Includes options set for [shared workflow start](#options-set-for-shared-workflow-start). Includes options set for [workflow start](#options-set-for-workflow-start). Includes options set for [payload input](#options-set-for-payload-input). -### temporal workflow fix-history-json: Updates an event history JSON file to the current format. +### temporal workflow fix-history-json: Updates an event history JSON file + +Reserialize an Event History JSON file: ``` temporal workflow fix-history-json \ - --source original.json \ - --target reserialized.json + --source /path/to/original.json \ + --target /path/to/reserialized.json ``` -Use the options listed below to change the command's behavior. - #### Options -* `--source`, `-s` (string) - Path to the input file. Required. -* `--target`, `-t` (string) - Path to the output file, or standard output if not set. +* `--source`, `-s` (string) - + Path to the original file. + Required. +* `--target`, `-t` (string) - + Path to the results file. + When omitted, output is sent to stdout. -### temporal workflow list: List Workflow Executions based on a Query. +### temporal workflow list: Show Workflow Executions -The `temporal workflow list` command provides a list of [Workflow Executions](/concepts/what-is-a-workflow-execution) -that meet the criteria of a given [Query](/concepts/what-is-a-query). -By default, this command returns up to 10 closed Workflow Executions. +List Workflow Executions. By default, this command returns up to 10 closed +Workflow Executions. The optional `--query` limits the output to Workflows +matching a Query: -`temporal workflow list --query=MyQuery` +``` +temporal workflow list \ + --query YourQuery` +``` -The command can also return a list of archived Workflow Executions. +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. -`temporal workflow list --archived` +View a list of archived Workflow Executions: -Use the command options below to change the information returned by this command. +``` +temporal workflow list \ + --archived +``` #### Options -* `--query`, `-q` (string) - Filter results using a SQL-like query. -* `--archived` (bool) - If set, will only query and list archived workflows instead of regular workflows. -* `--limit` (int) - Limit the number of items to print. +* `--query`, `-q` (string) - + Content for an SQL-like `QUERY` List Filter. +* `--archived` (bool) - + Limit output to archived Workflow Executions. +* `--limit` (int) - + Maximum number of Workflow Executions to display. -### temporal workflow query: Query a Workflow Execution. +### temporal workflow query: Retrieve Workflow Execution state -The `temporal workflow query` command is used to [Query](/concepts/what-is-a-query) a -[Workflow Execution](/concepts/what-is-a-workflow-execution) -by [ID](/concepts/what-is-a-workflow-id). +Send a Query to a Workflow Execution by Workflow ID to retrieve its state. +This synchronous operation exposes the internal state of a running Workflow +Execution, which constantly changes. You can query both running and completed +Workflow Executions: ``` temporal workflow query \ - --workflow-id MyWorkflowId \ - --name MyQuery \ - --input '{"MyInputKey": "MyInputValue"}' + --workflow-id YourWorkflowId + --type YourQueryType + --input '{"YourInputKey": "YourInputValue"}' ``` -Use the options listed below to change the command's behavior. - #### Options -* `--name` (string) - Query Type/Name. Required. Alias: `--type`. -* `--reject-condition` (string-enum) - Optional flag for rejecting Queries based on Workflow state. +* `--name` (string) - + Query Type/Name. + Required. + Alias: `--type`. +* `--reject-condition` (string-enum) - + Optional flag for rejecting Queries based on Workflow state. Options: not_open, not_completed_cleanly. Includes options set for [payload input](#options-set-for-payload-input). Includes options set for [workflow reference](#options-set-for-workflow-reference). -### temporal workflow reset: Resets a Workflow Execution by Event ID or reset type. +### temporal workflow reset: Move Workflow Execution history point -The temporal workflow reset command resets a [Workflow Execution](/concepts/what-is-a-workflow-execution). -A reset allows the Workflow to resume from a certain point without losing its parameters or [Event History](/concepts/what-is-an-event-history). +Reset a Workflow Execution so it can resume from a point in its Event History +without losing its progress up to that point: -The Workflow Execution can be set to a given [Event Type](/concepts/what-is-an-event): ``` -temporal workflow reset --workflow-id=meaningful-business-id --type=LastContinuedAsNew +temporal workflow reset \ + --workflow-id YourWorkflowId + --event-id YourLastEvent ``` -...or a specific any Event after `WorkflowTaskStarted`. +Start from where the Workflow Execution last continued as new: + ``` -temporal workflow reset --workflow-id=meaningful-business-id --event-id=MyLastEvent +temporal workflow reset \ + --workflow-id YourWorkflowId \ + --type LastContinuedAsNew ``` -For batch reset only FirstWorkflowTask, LastWorkflowTask or BuildId can be used. Workflow Id, run Id and event Id -should not be set. -Use the options listed below to change reset behavior. - -#### Options - -* `--workflow-id`, `-w` (string) - Workflow Id. Required for non-batch reset operations. -* `--run-id`, `-r` (string) - Run Id. -* `--event-id`, `-e` (int) - The Event Id for any Event after `WorkflowTaskStarted` you want to reset to (exclusive). It can be `WorkflowTaskCompleted`, `WorkflowTaskFailed` or others. -* `--reason` (string) - The reason why this workflow is being reset. Required. -* `--reapply-type` (string-enum) - *DEPRECATED* Use --reapply-exclude. Event types to reapply after the reset point. Options: All, Signal, None. Default: All. -* `--reapply-exclude` (string[]) - Event types to exclude from reapplication. Options: All, Signal, Update. -* `--type`, `-t` (string-enum) - Event type to which you want to reset. Options: FirstWorkflowTask, LastWorkflowTask, LastContinuedAsNew, BuildId. -* `--build-id` (string) - Only used if type is BuildId. Reset the first workflow task processed by this build id. Note that by default, this reset is allowed to be to a prior run in a chain of continue-as-new. -* `--query`, `-q` (string) - Start a batch reset to operate on Workflow Executions with given List Filter. -* `--yes`, `-y` (bool) - Confirm prompt to perform batch. Only allowed if query is present. - - - -### temporal workflow show: Show Event History for a Workflow Execution. -The `temporal workflow show` command provides the [Event History](/concepts/what-is-an-event-history) for a -[Workflow Execution](/concepts/what-is-a-workflow-execution). With JSON output specified, this output can be given to -an SDK to perform a replay. +For batch resets, limit your resets to FirstWorkflowTask, LastWorkflowTask, or +BuildId. Do not use Workflow IDs, run IDs, or event IDs with this command. + +Visit https://docs.temporal.io/visibility to read more about Search +Attributes and Query creation. + +#### Options + +* `--workflow-id`, `-w` (string) - + Workflow ID. + Required for non-batch reset operations. +* `--run-id`, `-r` (string) - + Run ID. +* `--event-id`, `-e` (int) - + Event ID to reset to. + Event must occur after `WorkflowTaskStarted`. + `WorkflowTaskCompleted`, `WorkflowTaskFailed`, etc. are valid. +* `--reason` (string) - + Reason for reset. + Required. +* `--reapply-type` (string-enum) - + Types of events to re-apply after reset point. + Deprecated. + Use --reapply-exclude instead. + Options: All, Signal, None. + Default: All. +* `--reapply-exclude` (string[]) - + Exclude these event types from re-application. + Options: All, Signal, Update. +* `--type`, `-t` (string-enum) - + The event type for the reset. + Options: FirstWorkflowTask, LastWorkflowTask, LastContinuedAsNew, BuildId. +* `--build-id` (string) - + A Build ID. + Use only with the BuildId `--type`. + Resets the first Workflow task processed by this ID. + By default, this reset may be in a prior run, earlier than a Continue + as New point. +* `--query`, `-q` (string) - + Content for an SQL-like `QUERY` List Filter. +* `--yes`, `-y` (bool) - + Don't prompt to confirm. + Only allowed when `--query` is present. + +### temporal workflow show: Display Event History + +Show a Workflow Execution's Event History. +When using JSON output (`--output json`), you may pass the results to an SDK +to perform a replay: -Use the options listed below to change the command's behavior. +``` +temporal workflow show \ + --workflow-id YourWorkflowId + --output json +``` #### Options -* `--follow`, `-f` (bool) - Follow the progress of a Workflow Execution in real time (does not apply - to JSON output). -* `--detailed` (bool) - If set when using text output, display events as sections with detail instead of simple table. +* `--follow`, `-f` (bool) - + Follow the Workflow Execution progress in real time. + Does not apply to JSON output. +* `--detailed` (bool) - + Display events as detailed sections instead of table. + Does not apply to JSON output. Includes options set for [workflow reference](#options-set-for-workflow-reference). -### temporal workflow signal: Signal Workflow Execution by Id. +### temporal workflow signal: Send a message to a Workflow Execution -The `temporal workflow signal` command is used to [Signal](/concepts/what-is-a-signal) a -[Workflow Execution](/concepts/what-is-a-workflow-execution) by [ID](/concepts/what-is-a-workflow-id). +Send an asynchronous notification (Signal) to a running Workflow Execution by +its Workflow ID. The Signal is written to the History. When you include +`--input`, that data is available for the Workflow Execution to consume: ``` temporal workflow signal \ - --workflow-id MyWorkflowId \ - --name MySignal \ - --input '{"MyInputKey": "MyInputValue"}' + --workflow-id YourWorkflowId \ + --name YourSignal \ + --input '{"YourInputKey": "YourInputValue"}' ``` -Use the options listed below to change the command's behavior. +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. #### Options -* `--name` (string) - Signal Name. Required. Alias: `--type`. +* `--name` (string) - + Signal name. + Required. + Alias: `--type`. Includes options set for [payload input](#options-set-for-payload-input). #### Options set for single workflow or batch: - -* `--workflow-id`, `-w` (string) - Workflow Id. Either this or query must be set. -* `--run-id`, `-r` (string) - Run Id. Cannot be set when query is set. -* `--query`, `-q` (string) - Start a batch to operate on Workflow Executions with given List Filter. Either this or - Workflow Id must be set. -* `--reason` (string) - Reason to perform batch. Only allowed if query is present unless the command specifies - otherwise. Defaults to message with the current user's name. -* `--yes`, `-y` (bool) - Confirm prompt to perform batch. Only allowed if query is present. - -### temporal workflow stack: Query a Workflow Execution for its stack trace. - -The `temporal workflow stack` command [Queries](/concepts/what-is-a-query) a -[Workflow Execution](/concepts/what-is-a-workflow-execution) with `__stack_trace` as the query type. -This returns a stack trace of all the threads or routines currently used by the workflow, and is -useful for troubleshooting. +* `--workflow-id`, `-w` (string) - + Workflow ID. + You must set either --workflow-id or --query. +* `--query`, `-q` (string) - + Content for an SQL-like `QUERY` List Filter. + You must set either --workflow-id or --query. +* `--run-id`, `-r` (string) - + Run ID. + Only use with --workflow-id. + Cannot use with --query. +* `--reason` (string) - + Reason to perform batch. + Only use with --query. + Defaults to user name. +* `--yes`, `-y` (bool) - + Don't prompt to confirm signaling. + Only allowed when --query is present. + +### temporal workflow stack: Trace a Workflow Execution + +Perform a Query on a Workflow Execution using a `__stack_trace`-type Query. +Display a stack trace of the threads and routines currently in use by the +Workflow for troubleshooting: ``` -temporal workflow stack --workflow-id MyWorkflowId +temporal workflow stack \ + --workflow-id YourWorkflowId ``` -Use the options listed below to change the command's behavior. - #### Options -* `--reject-condition` (string-enum) - Optional flag for rejecting Queries based on Workflow state. +* `--reject-condition` (string-enum) - + Optional flag to reject Queries based on Workflow state. Options: not_open, not_completed_cleanly. Includes options set for [workflow reference](#options-set-for-workflow-reference). -### temporal workflow start: Starts a new Workflow Execution. +### temporal workflow start: Initiate a Workflow Execution -The `temporal workflow start` command starts a new [Workflow Execution](/concepts/what-is-a-workflow-execution). The -Workflow and Run IDs are returned after starting the [Workflow](/concepts/what-is-a-workflow). +Start a new Workflow Execution. Returns the Workflow- and Run-IDs. ``` temporal workflow start \ - --workflow-id meaningful-business-id \ - --type MyWorkflow \ - --task-queue MyTaskQueue \ + --workflow-id YourWorkflowId \ + --type YourWorkflow \ + --task-queue YourTaskQueue \ --input '{"Input": "As-JSON"}' ``` #### Options set for shared workflow start: -* `--workflow-id`, `-w` (string) - Workflow Id. -* `--type` (string) - Workflow Type name. Required. Alias: `--name`. -* `--task-queue`, `-t` (string) - Workflow Task queue. Required. -* `--run-timeout` (duration) - Timeout of a Workflow Run. -* `--execution-timeout` (duration) - Timeout for a WorkflowExecution, including retries and ContinueAsNew tasks. -* `--task-timeout` (duration) - Start-to-close timeout for a Workflow Task. Default: 10s. -* `--search-attribute` (string[]) - Passes Search Attribute in key=value format. Use valid JSON formats for value. -* `--memo` (string[]) - Passes Memo in key=value format. Use valid JSON formats for value. +* `--workflow-id`, `-w` (string) - + Workflow ID. + If not supplied, the Service generates a unique ID. +* `--type` (string) - + Workflow Type name. + Required. + Alias: `--name`. +* `--task-queue`, `-t` (string) - + Workflow Task queue. + Required. +* `--run-timeout` (duration) - + Fail a Workflow Run if it lasts longer than `DURATION`. +* `--execution-timeout` (duration) - + Fail a WorkflowExecution if it lasts longer than `DURATION`. + This time-out includes retries and ContinueAsNew tasks. +* `--task-timeout` (duration) - + Fail a Workflow Task if it lasts longer than `DURATION`. + This is the Start-to-close timeout for a Workflow Task. + Default: 10s. +* `--search-attribute` (string[]) - + Search Attribute in `KEY=VALUE` format. + Keys must be identifiers, and values must be JSON values. + For example: 'YourKey={"your": "value"}'. + Can be passed multiple times. +* `--memo` (string[]) - + Memo using 'KEY="VALUE"' pairs. + Use JSON values. #### Options set for workflow start: -* `--cron` (string) - Cron schedule for the workflow. Deprecated - use schedules instead. -* `--fail-existing` (bool) - Fail if the workflow already exists. -* `--start-delay` (duration) - Specify a delay before the workflow starts. Cannot be used with a cron schedule. If the - workflow receives a signal or update before the delay has elapsed, it will begin immediately. -* `--id-reuse-policy` (string) - Allows the same Workflow Id to be used in a new Workflow Execution. Options: - AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning. +* `--cron` (string) - + Cron schedule for the Workflow. + Deprecated. + Use Schedules instead. +* `--fail-existing` (bool) - + Fail if the Workflow already exists. +* `--start-delay` (duration) - + Delay before starting the Workflow Execution. + Can't be used with cron schedules. + If the Workflow receives a signal or update prior to this time, the Workflow + Execution starts immediately. +* `--id-reuse-policy` (string) - + Re-use policy for the Workflow ID in new Workflow Executions. + Options: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning. #### Options set for payload input: -* `--input`, `-i` (string[]) - Input value (default JSON unless --input-payload-meta is non-JSON encoding). Can - be given multiple times for multiple arguments. Cannot be combined with --input-file. -* `--input-file` (string[]) - Reads a file as the input (JSON by default unless --input-payload-meta is non-JSON - encoding). Can be given multiple times for multiple arguments. Cannot be combined with --input. -* `--input-meta` (string[]) - Metadata for the input payload. Expected as key=value. If key is encoding, overrides the - default of json/plain. -* `--input-base64` (bool) - If set, assumes --input or --input-file are base64 encoded and attempts to decode. - -### temporal workflow terminate: Terminate Workflow Execution by ID or List Filter. - -The `temporal workflow terminate` command is used to terminate a -[Workflow Execution](/concepts/what-is-a-workflow-execution). Canceling a running Workflow Execution records a -`WorkflowExecutionTerminated` event as the closing Event in the workflow's Event History. Workflow code is oblivious to -termination. Use `temporal workflow cancel` if you need to perform cleanup in your workflow. +* `--input`, `-i` (string[]) - + Input value. + Use JSON content or set --input-meta to override. + Can't be combined with --input-file. + Can be passed multiple times to pass multiple arguments. +* `--input-file` (string[]) - + A path or paths for input file(s). + Use JSON content or set --input-meta to override. + Can't be combined with --input. + Can be passed multiple times to pass multiple arguments. +* `--input-meta` (string[]) - + Input payload metadata as a `KEY=VALUE` pair. + When the KEY is "encoding", this overrides the default ("json/plain"). + Can be passed multiple times. +* `--input-base64` (bool) - + Assume inputs are base64-encoded and attempt to decode them. + +### temporal workflow terminate: Forcefully end a Workflow Execution + +Terminate a Workflow Execution: -Executions may be terminated by [ID](/concepts/what-is-a-workflow-id) with an optional reason: ``` -temporal workflow terminate [--reason my-reason] --workflow-id MyWorkflowId +temporal workflow terminate \ + --reason YourReasonForTermination \ + --workflow-id YourWorkflowId ``` -...or in bulk via a visibility query [list filter](/concepts/what-is-a-list-filter): +The reason is optional and defaults to the current user's name. The reason +is stored in the Event History as part of the `WorkflowExecutionTerminated` +event. This becomes the closing Event in the Workflow Execution's history. + +Executions may be terminated in bulk via a visibility Query list filter: + ``` -temporal workflow terminate --query=MyQuery +temporal workflow terminate \ + --query YourQuery \ + --reason YourReasonForTermination ``` -Use the options listed below to change the behavior of this command. +Workflow code cannot see or respond to terminations. To perform clean-up work +in your Workflow code, use `temporal workflow cancel` instead. + +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. #### Options -* `--workflow-id`, `-w` (string) - Workflow Id. Either this or query must be set. -* `--run-id`, `-r` (string) - Run Id. Cannot be set when query is set. -* `--query`, `-q` (string) - Start a batch to terminate Workflow Executions with given List Filter. Either this or - Workflow Id must be set. -* `--reason` (string) - Reason for termination. Defaults to message with the current user's name. -* `--yes`, `-y` (bool) - Confirm prompt to perform batch. Only allowed if query is present. +* `--workflow-id`, `-w` (string) - + Workflow ID. + You must set either --workflow-id or --query. +* `--query`, `-q` (string) - + Content for an SQL-like `QUERY` List Filter. + You must set either --workflow-id or --query. +* `--run-id`, `-r` (string) - + Run ID. + Can only be set with --workflow-id. + Do not use with --query. +* `--reason` (string) - + Reason for termination. + Defaults to message with the current user's name. +* `--yes`, `-y` (bool) - + Don't prompt to confirm termination. + Can only be used with --query. -### temporal workflow trace: Terminate Workflow Execution by ID or List Filter. +### temporal workflow trace: Workflow Execution live progress -The `temporal workflow trace` command display the progress of a [Workflow Execution](/concepts/what-is-a-workflow-execution) and its child workflows with a trace. -This view provides a great way to understand the flow of a workflow. +Display the progress of a Workflow Execution and its child workflows with a +real-time trace. This view helps you understand how Workflows are proceeding: -Use the options listed below to change the behavior of this command. +``` +temporal workflow trace \ + --workflow-id YourWorkflowId +``` #### Options -* `--fold` (string[]) - Statuses for which Child Workflows will be folded in (this will reduce the number of information fetched and displayed). Case-insensitive and ignored if no-fold supplied. Available values: running, completed, failed, canceled, terminated, timedout, continueasnew. -* `--no-fold` (bool) - Disable folding. All Child Workflows within the set depth will be fetched and displayed. -* `--depth` (int) - Depth of child workflows to fetch. Use -1 to fetch child workflows at any depth. Default: -1. -* `--concurrency` (int) - Number of concurrent workflow histories that will be requested at any given time. Default: 10. +* `--fold` (string[]) - + Fold away Child Workflows with the specified statuses. + Case-insensitive. + Ignored if --no-fold supplied. + Available values: running, completed, failed, canceled, terminated, + timedout, continueasnew. + Can be passed multiple times. +* `--no-fold` (bool) - + Disable folding. + Fetch and display Child Workflows within the set depth. +* `--depth` (int) - + Set depth for your Child Workflow fetches. + Pass -1 to fetch child workflows at any depth. + Default: -1. +* `--concurrency` (int) - + Number of Workflow Histories to fetch at a time. + Default: 10. Includes options set for [workflow reference](#options-set-for-workflow-reference). -### temporal workflow update: Updates a running workflow synchronously. +### temporal workflow update: Synchronously run a Workflow update handler -The `temporal workflow update` command is used to synchronously [Update](/concepts/what-is-an-update) a -[WorkflowExecution](/concepts/what-is-a-workflow-execution) by [ID](/concepts/what-is-a-workflow-id). +Send a message to a Workflow Execution to invoke an update handler. An update +can change the state of a Workflow Execution and return a response: ``` temporal workflow update \ - --workflow-id MyWorkflowId \ - --name MyUpdate \ - --input '{"Input": "As-JSON"}' + --workflow-id YourWorkflowId \ + --name YourUpdate \ + --input '{"Input": "As-JSON"}' ``` -Use the options listed below to change the command's behavior. - #### Options -* `--name` (string) - Update Name. Required. Alias: `--type`. -* `--workflow-id`, `-w` (string) - Workflow Id. Required. -* `--update-id` (string) - Update ID. If unset, default to a UUID. -* `--run-id`, `-r` (string) - Run Id. If unset, the currently running Workflow Execution receives the Update. -* `--first-execution-run-id` (string) - Send the Update to the last Workflow Execution in the chain that started - with this Run Id. +* `--name` (string) - + Handler method name. + Required. + Alias: `--type`. +* `--workflow-id`, `-w` (string) - + Workflow ID. + Required. +* `--update-id` (string) - + Update ID. + If unset, defaults to a UUID. + Must be unique per Workflow Execution. +* `--run-id`, `-r` (string) - + Run ID. + If unset, updates the currently-running Workflow Execution. +* `--first-execution-run-id` (string) - + Parent Run ID. + The update is sent to the last Workflow Execution in the chain started + with this Run ID. Includes options set for [payload input](#options-set-for-payload-input). diff --git a/temporalcli/commandsmd/parse.go b/temporalcli/commandsmd/parse.go index 5c4cd175..767e794e 100644 --- a/temporalcli/commandsmd/parse.go +++ b/temporalcli/commandsmd/parse.go @@ -260,9 +260,6 @@ func (c *CommandOption) parseBulletLine(bullet string) error { // Go over trailing sentences in description to see if they're attributes and // take them off if they are. for { - if !strings.HasSuffix(c.Desc, ".") { - return fmt.Errorf("description doesn't end with period") - } dot := strings.LastIndex(c.Desc[:len(c.Desc)-1], ". ") if dot == -1 { return nil