From c1718f76bbc71a43ed8027cddc0755e43f89075a Mon Sep 17 00:00:00 2001 From: Josh Berry Date: Mon, 6 May 2024 17:52:39 -0700 Subject: [PATCH 01/52] Start updating the --help text output --- temporalcli/commands.gen.go | 360 +++++++++++++-------------- temporalcli/commandsmd/commands.md | 377 +++++++++++++++-------------- temporalcli/commandsmd/parse.go | 3 - 3 files changed, 365 insertions(+), 375 deletions(-) diff --git a/temporalcli/commands.gen.go b/temporalcli/commands.gen.go index cc5b8797..fecd6eaa 100644 --- a/temporalcli/commands.gen.go +++ b/temporalcli/commands.gen.go @@ -31,7 +31,7 @@ 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.Short = "Temporal command-line interface and development server" s.Command.Long = "" s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalActivityCommand(cctx, &s).Command) @@ -42,19 +42,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", "", "Read additional options from the `ENV` environment. (See \"temporal env --help\" for more about environments.) Default: default.") 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", "", "Read/store per-environment configuration in `PATH` (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().Var(&s.LogLevel, "log-level", "Log level. Default is \"info\" for most commands and \"warn\" for the development server. Accepted values: debug, info, warn, error, never.") + s.Command.PersistentFlags().StringVar(&s.LogFormat, "log-format", "", "Emit log messages in \"text\" or \"json\" format. Default is \"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", "Emit output in the `FMT` format. Does not affect logs; use --log-format instead. 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.Command.PersistentFlags().Var(&s.TimeFormat, "time-format", "Emit timestamps in the `FMT` 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", "Colorize output. Does not affect logs. Accepted values: always, never, auto.") + s.Command.PersistentFlags().BoolVar(&s.NoJsonShorthandPayloads, "no-json-shorthand-payloads", false, "Show all payloads as raw payloads even if they are JSON.") s.initCommand(cctx) return &s } @@ -69,7 +69,7 @@ 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.Short = "Complete or fail an Activity" s.Command.Long = "" s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalActivityCompleteCommand(cctx, &s).Command) @@ -83,8 +83,8 @@ type TemporalActivityCompleteCommand struct { Command cobra.Command WorkflowReferenceOptions ActivityId string - Identity string Result string + Identity string } func NewTemporalActivityCompleteCommand(cctx *CommandContext, parent *TemporalActivityCommand) *TemporalActivityCompleteCommand { @@ -92,7 +92,7 @@ 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" } else { @@ -100,11 +100,11 @@ func NewTemporalActivityCompleteCommand(cctx *CommandContext, parent *TemporalAc } 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.") + s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "`ID` of the Activity to be completed.") _ = 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).") + s.Command.Flags().StringVar(&s.Result, "result", "", "Result `JSON` with which to complete the Activity.") _ = 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,7 +128,7 @@ 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" } else { @@ -136,11 +136,11 @@ func NewTemporalActivityFailCommand(cctx *CommandContext, parent *TemporalActivi } 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.") + s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "`ID` of the Activity to be failed.") _ = 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.Reason, "reason", "", "Reason for failing the Activity.") + s.Command.Flags().StringVar(&s.Detail, "detail", "", "`JSON` data describing the reason for failing the Activity") + 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 { cctx.Options.Fail(err) @@ -160,7 +160,7 @@ func NewTemporalBatchCommand(cctx *CommandContext, parent *TemporalCommand) *Tem s.Parent = parent s.Command.Use = "batch" s.Command.Short = "Manage Batch Jobs" - s.Command.Long = "Batch commands change multiple Workflow Executions." + s.Command.Long = "Batch commands change multiple Workflow Executions at once." s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalBatchDescribeCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalBatchListCommand(cctx, &s).Command) @@ -180,11 +180,11 @@ 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.\n\n\x1b[1mtemporal batch describe --job-id=MyJobId\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.\n\n`temporal batch describe --job-id=MyJobId`" } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.JobId, "job-id", "", "The Batch Job Id to describe.") @@ -210,12 +210,12 @@ func NewTemporalBatchListCommand(cctx *CommandContext, parent *TemporalBatchComm s.Command.Use = "list [flags]" 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 = "List all Batch Jobs. Batch Jobs can be returned for an entire Cluster or a single Namespace.\n\n\x1b[1mtemporal batch list --namespace=MyNamespace\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 = "List all Batch Jobs. Batch Jobs can be returned for an entire Cluster or a single Namespace.\n\n`temporal batch list --namespace=MyNamespace`" } 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, "Show only the first `N` Batch Jobs in the list.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -238,9 +238,9 @@ func NewTemporalBatchTerminateCommand(cctx *CommandContext, parent *TemporalBatc s.Command.Use = "terminate [flags]" s.Command.Short = "Terminate 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 = "The temporal batch terminate command terminates a Batch Job with the provided Job Id.\nYou must provide a reason for terminating the Batch Job, which is stored for future reference.\n\n\x1b[1mtemporal batch terminate --job-id=MyJobId --reason=JobReason\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 = "The temporal batch terminate command terminates a Batch Job with the provided Job Id.\nYou must provide a reason for terminating the Batch Job, which is stored for future reference.\n\n`temporal batch terminate --job-id=MyJobId --reason=JobReason`" } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.JobId, "job-id", "", "The Batch Job Id to terminate.") @@ -264,8 +264,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 allow you to specify named sets of flags to apply by default. Most commonly, environments are used to override the \x1b[1m--address\x1b[0m flag to point to different Temporal Server instances (for example, having different \"dev\" and \"prod\" environments).\n\nUse the \x1b[1m--env\x1b[0m option with any \x1b[1mtemporal\x1b[0m command to choose the environment. You can also specify the environment using the \x1b[1mTEMPORAL_ENV\x1b[0m environment variable. If no environment is specified, the 'default' environment is used." + } else { + s.Command.Long = "Environments allow you to specify named sets of flags to apply by default. Most commonly, environments are used to override the `--address` flag to point to different Temporal Server instances (for example, having different \"dev\" and \"prod\" environments).\n\nUse the `--env` option with any `temporal` command to choose the environment. You can also specify the environment using the `TEMPORAL_ENV` environment variable. If no environment is specified, the 'default' environment is used." + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalEnvDeleteCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalEnvGetCommand(cctx, &s).Command) @@ -285,14 +289,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" } 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.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", "", "The name of the property") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -312,14 +316,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 = "Print 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." } 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.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", "", "The name of the property") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -338,7 +342,7 @@ 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.Short = "Print all environments" s.Command.Long = "List all environments." s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { @@ -361,15 +365,15 @@ 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." } 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.Args = cobra.MaximumNArgs(2) - 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", "", "The name of the property (required)") + s.Command.Flags().StringVarP(&s.Value, "value", "v", "", "The value to set the property to (required)") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -388,12 +392,8 @@ func NewTemporalOperatorCommand(cctx *CommandContext, parent *TemporalCommand) * var s TemporalOperatorCommand s.Parent = parent s.Command.Use = "operator" - s.Command.Short = "Manage a Temporal deployment." - 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" - } 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.Short = "Manage a Temporal deployment" + s.Command.Long = "Operator commands perform actions on Namespaces, Search Attributes, and Temporal Clusters." s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalOperatorClusterCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalOperatorNamespaceCommand(cctx, &s).Command) @@ -411,12 +411,8 @@ 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." - 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" - } 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.Short = "Operations for running a Temporal Cluster" + s.Command.Long = "Cluster commands perform actions on Temporal Clusters." s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalOperatorClusterDescribeCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalOperatorClusterHealthCommand(cctx, &s).Command) @@ -439,13 +435,9 @@ func NewTemporalOperatorClusterDescribeCommand(cctx *CommandContext, parent *Tem s.Command.DisableFlagsInUseLine = true s.Command.Use = "describe [flags]" s.Command.Short = "Describe a cluster" - if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster describe\x1b[0m command shows information about the Cluster." - } else { - s.Command.Long = "`temporal operator cluster describe` command shows information about the Cluster." - } + s.Command.Long = "" 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 extra details") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -464,12 +456,8 @@ 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" - if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster health\x1b[0m command checks the health of the Frontend Service." - } else { - s.Command.Long = "`temporal operator cluster health` command checks the health of the Frontend Service." - } + s.Command.Short = "Check the health of a cluster" + s.Command.Long = "" s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -490,14 +478,10 @@ func NewTemporalOperatorClusterListCommand(cctx *CommandContext, parent *Tempora s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "list [flags]" - s.Command.Short = "List all clusters" - if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster list\x1b[0m command prints a list of all remote Clusters on the system." - } else { - s.Command.Long = "`temporal operator cluster list` command prints a list of all remote Clusters on the system." - } + s.Command.Short = "List all remote clusters" + s.Command.Long = "" 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, "Show only the first `N` clusters in the list.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -517,12 +501,8 @@ func NewTemporalOperatorClusterRemoveCommand(cctx *CommandContext, parent *Tempo s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "remove [flags]" - s.Command.Short = "Remove a cluster" - if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal operator cluster remove\x1b[0m command removes a remote Cluster from the system." - } else { - s.Command.Long = "`temporal operator cluster remove` command removes a remote Cluster from the system." - } + s.Command.Short = "Remove a remote cluster" + s.Command.Long = "" s.Command.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.Name, "name", "", "Name of cluster.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "name") @@ -571,16 +551,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 a remote cluster" if hasHighlighting { s.Command.Long = "\x1b[1mtemporal operator cluster upsert\x1b[0m command allows the user to add or update a remote Cluster." } else { s.Command.Long = "`temporal operator cluster upsert` command allows the user to add or update a remote Cluster." } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVar(&s.FrontendAddress, "frontend-address", "", "IP address to bind the frontend service to.") + s.Command.Flags().StringVar(&s.FrontendAddress, "frontend-address", "", "`IP` address to bind the frontend service to.") _ = 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, "Enable cross-cluster connection.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -598,7 +578,7 @@ 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 = "Operations on Namespaces" 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" } else { @@ -634,26 +614,26 @@ 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" } 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.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().StringVar(&s.Data, "data", "", "Namespace data in key=value format. Use JSON for values.") - 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().StringVar(&s.ActiveCluster, "active-cluster", "", "Active cluster name") + s.Command.Flags().StringArrayVar(&s.Cluster, "cluster", nil, "Cluster names. \"--cluster\" may be passed multiple times to specify multiple clusters.") + s.Command.Flags().StringVar(&s.Data, "data", "", "Namespace data in `KEY=VALUE` format, separated by commas. `KEY` and `VALUE` may be arbitrary strings.") + 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, "Enable cross-region replication for this namespace.") 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", "", "`URI` at which to archive history. Cannot be changed after archival is first enabled.") s.Command.Flags().DurationVar(&s.Retention, "retention", 259200000*time.Millisecond, "Length of time a closed Workflow is preserved 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", "", "`URI` at which to archive visibility data. Cannot be changed after archival is first enabled.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -673,10 +653,10 @@ 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.Short = "Delete an existing Namespace" s.Command.Long = "The temporal operator namespace delete command deletes a given Namespace from the system." 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, "Don't ask for confirmation.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -696,14 +676,14 @@ 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 by its name or ID" 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" } 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.Args = cobra.MaximumNArgs(1) - s.Command.Flags().StringVar(&s.NamespaceId, "namespace-id", "", "Namespace ID.") + s.Command.Flags().StringVar(&s.NamespaceId, "namespace-id", "", "Namespace ID") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -722,7 +702,7 @@ 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.Short = "List all Namespaces" s.Command.Long = "The temporal operator namespace list command lists all Namespaces on the Server." s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { @@ -754,26 +734,26 @@ 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" } 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.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.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().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, "Set a `KEY=VALUE` pair in namespace data. `KEY` and `VALUE` may be arbitrary strings, but JSON is recommended for `VALUE`. May be used multiple times to set multiple pairs.") + 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, "Enable cross-region replication on this namespace.") 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().DurationVar(&s.Retention, "retention", 0, "Length of time a closed Workflow is preserved before deletion.") + s.Command.Flags().StringVar(&s.HistoryUri, "history-uri", "", "Archive history to this `URI`. Cannot be changed after archival is first enabled.") + s.Command.Flags().DurationVar(&s.Retention, "retention", 0, "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 information to this `URI`. Cannot be changed after archival is first enabled.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -791,7 +771,7 @@ 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.Short = "Operations for Search Attributes" s.Command.Long = "Search Attribute commands enable operations for the creation, listing, and removal of Search Attributes." s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalOperatorSearchAttributeCreateCommand(cctx, &s).Command) @@ -812,7 +792,7 @@ 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." } else { @@ -841,11 +821,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 all 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 = "\x1b[1mtemporal operator search-attribute list\x1b[0m displays a list of all Search Attributes that can be used in list Workflow Queries." } else { - s.Command.Long = "`temporal operator search-attribute list` displays a list of all Search Attributes." + s.Command.Long = "`temporal operator search-attribute list` displays a list of all Search Attributes that can be used in list Workflow Queries." } s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { @@ -868,7 +848,7 @@ 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 attribute metadata" if hasHighlighting { s.Command.Long = "\x1b[1mtemporal operator search-attribute remove\x1b[0m command removes custom Search Attribute metadata." } else { @@ -877,7 +857,7 @@ func NewTemporalOperatorSearchAttributeRemoveCommand(cctx *CommandContext, paren s.Command.Args = cobra.NoArgs s.Command.Flags().StringArrayVar(&s.Name, "name", nil, "Search Attribute name.") _ = 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 ask for confirmation.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -896,7 +876,7 @@ 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.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.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalScheduleBackfillCommand(cctx, &s).Command) @@ -943,7 +923,7 @@ 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 a past time range of 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" } else { @@ -982,20 +962,20 @@ 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.DurationVar(&v.CatchupWindow, "catchup-window", 0, "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.Calendar, "calendar", nil, "Calendar specification in JSON, e.g. `{\"dayOfWeek\":\"Fri\",\"hour\":\"17\",\"minute\":\"5\"}`") + f.DurationVar(&v.CatchupWindow, "catchup-window", 0, "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.DurationVar(&v.Jitter, "jitter", 0, "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.DurationVar(&v.Jitter, "jitter", 0, "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.StartTime, "start-time", "Overall schedule start time") + f.StringVar(&v.TimeZone, "time-zone", "", "Interpret all calendar specs in 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 a Search Attribute for the schedule in `KEY=VALUE` format. `KEY` must be a string identifier (no quotes) and `VALUE` must be a JSON value. May be passed multiple times to set multiple Search Attributes.") + f.StringArrayVar(&v.ScheduleMemo, "schedule-memo", nil, "Set a memo for the schedule in `KEY=VALUE` format. `KEY` must be a string identifier (no quotes) and `VALUE` must be a JSON value. May be passed multiple times to set multiple memo values.") } type TemporalScheduleCreateCommand struct { @@ -1013,7 +993,7 @@ 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." } else { @@ -1044,7 +1024,7 @@ 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 = "Delete 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." } else { @@ -1071,7 +1051,7 @@ 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 = "Get Schedule configuration and current 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." } else { @@ -1099,15 +1079,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 = "List all Schedules" if hasHighlighting { s.Command.Long = "The \x1b[1mtemporal schedule list\x1b[0m command lists all Schedules in a namespace." } else { s.Command.Long = "The `temporal schedule list` command lists all Schedules in a namespace." } 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, "Emit detailed information.") + s.Command.Flags().BoolVar(&s.ReallyLong, "really-long", false, "Emit even more detailed information that's not usable in table form.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1130,7 +1110,7 @@ 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" } else { @@ -1140,7 +1120,7 @@ func NewTemporalScheduleToggleCommand(cctx *CommandContext, parent *TemporalSche 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.Unpause, "unpause", false, "Unpauses the schedule.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1161,7 +1141,7 @@ 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.Short = "Trigger a schedule to run immediately" s.Command.Long = "" s.Command.Args = cobra.NoArgs s.ScheduleIdOptions.buildFlags(cctx, s.Command.Flags()) @@ -1189,7 +1169,7 @@ 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.Short = "Update 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.Args = cobra.NoArgs s.ScheduleConfigurationOptions.buildFlags(cctx, s.Command.Flags()) @@ -1214,7 +1194,7 @@ 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" } else { @@ -1249,7 +1229,7 @@ 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" } else { @@ -1288,7 +1268,7 @@ 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." } else { @@ -1317,7 +1297,7 @@ func NewTemporalTaskQueueDescribeCommand(cctx *CommandContext, parent *TemporalT s.Parent = parent s.Command.DisableFlagsInUseLine = true s.Command.Use = "describe [flags]" - s.Command.Short = "Provides information for Workers that have recently polled on this Task Queue." + s.Command.Short = "Show Workers that have recently polled on a Task Queue" if hasHighlighting { s.Command.Long = "The \x1b[1mtemporal task-queue describe\x1b[0m command 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\n\x1b[1mtemporal task-queue describe --task-queue=MyTaskQueue --task-queue-type=\"activity\"\x1b[0m\n\nUse the options listed below to modify what this command returns." } else { @@ -1350,7 +1330,7 @@ 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." + s.Command.Short = "Show which Build IDs are available on a Task Queue" 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.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.") @@ -1377,7 +1357,7 @@ 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." + s.Command.Short = "Show worker Build ID versions on a Task Queue" s.Command.Long = "Fetch the sets of compatible build IDs associated with a Task Queue and associated information." s.Command.Args = cobra.NoArgs s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task queue name.") @@ -1402,7 +1382,7 @@ 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.Short = "List a Task Queue's partitions" 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.Args = cobra.NoArgs s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task queue name.") @@ -1424,7 +1404,7 @@ 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." + s.Command.Short = "Operations to manage Build ID versions on a Task Queue" 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.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalTaskQueueUpdateBuildIdsAddNewCompatibleCommand(cctx, &s).Command) @@ -1448,7 +1428,7 @@ 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.Short = "Add a new build ID compatible with an existing ID to a Task Queue's 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.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "The new build id to be added.") @@ -1478,7 +1458,7 @@ 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.Short = "Add a new default (incompatible) build ID to a Task Queue's 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.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "The new build id to be added.") @@ -1505,7 +1485,7 @@ 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.Short = "Promote a 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.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.") @@ -1532,7 +1512,7 @@ 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.Short = "Promote a build ID set to become the default for a Task Queue" s.Command.Long = "If the set is already the default, this command has no effect." s.Command.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "An existing build id whose containing set will be promoted.") @@ -1607,7 +1587,7 @@ 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." } else { @@ -1645,7 +1625,7 @@ 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 = "Cancel a 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." } else { @@ -1672,7 +1652,7 @@ 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 = "Count 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." } else { @@ -1699,7 +1679,7 @@ 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 = "Delete a 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." } else { @@ -1739,7 +1719,7 @@ 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 information about a Workflow Execution" 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." } else { @@ -1771,7 +1751,7 @@ 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 a new Workflow Execution and prints its progress" 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" } else { @@ -1802,7 +1782,7 @@ 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 to the current format" 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." } else { @@ -1833,7 +1813,7 @@ 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 = "List Workflow Executions based on a Query" 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." } else { @@ -1865,7 +1845,7 @@ 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 = "Query a Workflow Execution" 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." } else { @@ -1905,7 +1885,7 @@ 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 = "Reset a Workflow Execution to an older point in history" 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." } else { @@ -1923,7 +1903,7 @@ func NewTemporalWorkflowResetCommand(cctx *CommandContext, parent *TemporalWorkf 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().BoolVarP(&s.Yes, "yes", "y", false, "Don't ask for confirmation. (Note: Only allowed if --query is present)") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -1944,7 +1924,7 @@ 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 = "Show Event History for a Workflow Execution" 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." } else { @@ -1970,11 +1950,11 @@ type SingleWorkflowOrBatchOptions struct { } 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.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 --query 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.BoolVarP(&v.Yes, "yes", "y", false, "Don't ask for confirmation. (Note: Only allowed if --query is present)") } type TemporalWorkflowSignalCommand struct { @@ -1990,7 +1970,7 @@ 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 = "Signal 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." } else { @@ -2021,7 +2001,7 @@ 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 = "Show the stack trace of 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." } else { @@ -2051,14 +2031,14 @@ 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") f.StringVar(&v.Type, "type", "", "Workflow Type name.") _ = cobra.MarkFlagRequired(f, "type") f.StringVarP(&v.TaskQueue, "task-queue", "t", "", "Workflow Task queue.") _ = cobra.MarkFlagRequired(f, "task-queue") - f.DurationVar(&v.RunTimeout, "run-timeout", 0, "Timeout of a Workflow Run.") - f.DurationVar(&v.ExecutionTimeout, "execution-timeout", 0, "Timeout for a WorkflowExecution, including retries and ContinueAsNew tasks.") - f.DurationVar(&v.TaskTimeout, "task-timeout", 10000*time.Millisecond, "Start-to-close timeout for a Workflow Task.") + f.DurationVar(&v.RunTimeout, "run-timeout", 0, "Fail a Workflow Run if it takes longer than `DURATION`.") + f.DurationVar(&v.ExecutionTimeout, "execution-timeout", 0, "Fail a WorkflowExecution if it takes longer than `DURATION`, including retries and ContinueAsNew tasks.") + f.DurationVar(&v.TaskTimeout, "task-timeout", 0, "Fail a Workflow Task if it takes longer than `DURATION`. (Start-to-close timeout for a Workflow Task.) Default: 10s.") 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.") } @@ -2071,10 +2051,10 @@ 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.DurationVar(&v.StartDelay, "start-delay", 0, "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.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.DurationVar(&v.StartDelay, "start-delay", 0, "Wait before starting the Workflow. Cannot be used with a cron schedule. If the Workflow receives a signal or update before the delay has elapsed, it will start immediately.") + f.StringVar(&v.IdReusePolicy, "id-reuse-policy", "", "Allow the same Workflow Id to be used in a new Workflow Execution. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning.") } type PayloadInputOptions struct { @@ -2085,10 +2065,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 (default JSON unless --input-meta is non-JSON encoding). Can be passed multiple times for multiple arguments. Cannot be combined with --input-file.") + f.StringArrayVar(&v.InputFile, "input-file", nil, "Read `PATH` as the input value (JSON by default unless --input-meta is non-JSON encoding). Can be passed multiple times for multiple arguments. Cannot be combined with --input.") + f.StringArrayVar(&v.InputMeta, "input-meta", nil, "Metadata for the input payload, specified as a `KEY=VALUE` pair. If KEY is \"encoding\", overrides the default of \"json/plain\". Pass multiple --input-meta options to set multiple pairs.") + f.BoolVar(&v.InputBase64, "input-base64", false, "Assume inputs are base64-encoded and attempt to decode them.") } type TemporalWorkflowStartCommand struct { @@ -2104,7 +2084,7 @@ 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 = "Start a new 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" } else { @@ -2137,7 +2117,7 @@ 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 = "Terminate 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." } else { @@ -2146,7 +2126,7 @@ func NewTemporalWorkflowTerminateCommand(cctx *CommandContext, parent *TemporalW 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.Query, "query", "q", "", "Start a batch to terminate Workflow Executions with the `QUERY` List Filter. Either this or Workflow Id must be set.") 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.Run = func(c *cobra.Command, args []string) { @@ -2172,18 +2152,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 = "Interactively show the progress of a Workflow Execution" 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 = "The \x1b[1mtemporal workflow trace\x1b[0m command displays the progress of a Workflow Execution and its child workflows with a real-time 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." } 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 = "The `temporal workflow trace` command displays the progress of a Workflow Execution and its child workflows with a real-time 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.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().StringArrayVar(&s.Fold, "fold", nil, "Fold Child Workflows with the specified `STATUS`. To specify multiple statuses, pass --fold multiple times. This will reduce the amount of information fetched and displayed. Case-insensitive. 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().IntVar(&s.Depth, "depth", -1, "Fetch up to N Child Workflows deep. Use -1 to fetch child workflows at any depth.") + s.Command.Flags().IntVar(&s.Concurrency, "concurrency", 10, "Fetch up to N Workflow Histories at a time.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -2208,7 +2188,7 @@ 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 = "Update a running workflow synchronously" 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." } else { @@ -2218,11 +2198,11 @@ func NewTemporalWorkflowUpdateCommand(cctx *CommandContext, parent *TemporalWork s.PayloadInputOptions.buildFlags(cctx, s.Command.Flags()) s.Command.Flags().StringVar(&s.Name, "name", "", "Update Name.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "name") - s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow Id.") + s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow `ID`.") _ = 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, 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 `ID`.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) diff --git a/temporalcli/commandsmd/commands.md b/temporalcli/commandsmd/commands.md index 175feef9..2cc48cd4 100644 --- a/temporalcli/commandsmd/commands.md +++ b/temporalcli/commandsmd/commands.md @@ -9,8 +9,7 @@ This document has a specific structure used by a parser. Here are the rules: * Each command is a `### : ` heading. Command is full command path including parent commands. * Heading must be a single line. - * will have all up until the leading "[" as the name and the bracket-and-post-bracket content as just - additional "use" info. This would be used to document positional arguments. + * will have all words up to the leading "[" as the full command name. The remaining content between "[" and ": " (if any) is shown as part of the example usage. * Contents of each command section up to `#### Options` is the long description of the command. * End of long description can have XML comment section that has `*` bulleted attributes (one line per bullet): * `* has-init` - Will assume an `initCommand` method is on the command @@ -21,8 +20,12 @@ This document has a specific structure used by a parser. Here are the rules: * Each bullet is `* () - . `. * `` is `` `--` `` and can optionally be followed by ``, `-` ``. * `` must be one of `bool`, `duration`, `int`, `string`, `string[]`, `string-enum`, `timestamp`, TODO: more - * `` can be just about anything so long as it doesn't match trailing attributes. Any wrap - around to newlines + two-space indention is trimmed to a single space. + * `` can be just about anything, but note the following: + * It must not match trailing attributes. + * Any wraparound to newlines + two-space indention is trimmed to a single space. + * Using `code spans` will cause Cobra to assume the `code span` is the option's metavariable. For example, `ENV` is the metavariable in the following: + * `--env (string) - Read additional flags from the \`ENV\` environment.` + * In the above, Cobra will print: `--env ENV Read additional flags from the ENV environment` * `` can be: * `Required.` - Marks the option as required. * `Default: .` - Sets the default value of the option. No default means zero value of the type. @@ -36,12 +39,35 @@ This document has a specific structure used by a parser. Here are the rules: shareable options set. Copy/paste is acceptable. * Keep commands in alphabetical order. * Commands that have subcommands cannot be run on their own. -* Keep lines at 120 chars if possible. -* Add punctuation even at the end of phrases. + +Editorial standards for writing help text: + +* A command's short description must not end in a period. +* A command's long description should show example usages of the command. +* Use imperative-form verbs whereever possible: + * Good: `Pause or unpause a Schedule.` + * Bad: `This command pauses or unpauses a Schedule.` + +For options/flags, these additional standards apply: + +* Verb tense/sentence structure: +* For optional flags, use complete sentences with imperative-form verbs. (Prefer them for required flags, as well.) +* If a flag can be passed multiple times, say this explicitly in the usage text. +* Do not rely on the flag type (e.g. `string`, `bool`, etc.) being shown to the user. It is hidden if a `META-VARIABLE` is used. +* Where possible, a `META-VARIABLE` in all caps and wrapped in `\``s should be used to describe/reference the content to be passed to a particular flag. +* Use `code spans` only for meta-variables. To reference other options or specify literal values, use double quotes. +* Avoid parentheticals unless absolutely necessary. + +Examples showing correct/incorrect usage text for the optional `--history-uri` flag: +* Good: `Archive history at \`URI\`. Cannot be changed after archival is enabled.` +* Bad: Incomplete sentence: `History archival \`URI\`. Cannot be changed after archival is enabled.` +* Bad: Wrong verb tense: `Archives history at \`URI\`. Cannot be changed after archival is enabled.` +* Bad: No metavariable: `Archive history at the specified URI. Cannot be changed after archival is enabled.` +* Bad: Unnecessary parenthetical: `Archive history at \`URI\` (note: cannot be changed after archival is enabled).` --> -### temporal: Temporal command-line interface and development server. +### temporal: Temporal command-line interface and development server #### 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. +* `--active-cluster` (string) - Active cluster name +* `--cluster` (string[]) - Cluster names +* `--data` (string[]) - Set a `KEY=VALUE` pair in namespace data. `KEY` and `VALUE` may be arbitrary strings, but JSON is recommended for `VALUE`. May be used multiple times to set multiple pairs. +* `--description` (string) - Namespace description +* `--email` (string) - Owner email +* `--promote-global` (bool) - Enable cross-region replication on this 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. +* `--history-uri` (string) - Archive history to this `URI`. Cannot be changed after archival is first 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). +* `--visibility-uri` (string) - Archive visibility information to this `URI`. Cannot be changed after archival is first enabled. -### temporal operator search-attribute: Operations applying to Search Attributes +### temporal operator search-attribute: Operations for Search Attributes Search Attribute commands enable operations for the creation, listing, and removal of Search Attributes. -### temporal operator search-attribute create: Adds one or more custom Search Attributes +### temporal operator search-attribute create: Add custom Search Attributes `temporal operator search-attribute create` command adds one or more custom Search Attributes. @@ -391,20 +405,20 @@ Search Attribute commands enable operations for the creation, listing, and remov * `--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 all Search Attributes -`temporal operator search-attribute list` displays a list of all Search Attributes. +`temporal operator search-attribute list` displays a list of all Search Attributes that can be used in list Workflow Queries. -### temporal operator search-attribute remove: Removes custom search attribute metadata only +### temporal operator search-attribute remove: Remove custom search attribute metadata `temporal operator search-attribute remove` command removes custom Search Attribute metadata. #### Options * `--name` (string[]) - Search Attribute name. Required. -* `--yes`, `-y` (bool) - Confirm prompt to perform deletion. +* `--yes`, `-y` (bool) - Don't ask for confirmation. -### temporal schedule: Perform operations on Schedules. +### temporal schedule: Perform operations on Schedules Schedule commands allow the user to create, use, and update Schedules. Schedules allow starting Workflow Execution at regular times. @@ -413,7 +427,7 @@ Schedules allow starting Workflow Execution at regular times. Includes options set for [client](#options-set-for-client). -### temporal schedule backfill: Backfills a past time range of actions. +### temporal schedule backfill: Backfill 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. @@ -448,7 +462,7 @@ Example: * `--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. @@ -468,20 +482,20 @@ Actions will be executed at any time specified in the Schedule. #### 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. +* `--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. +* `--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. +* `--start-time` (timestamp) - Overall schedule start time +* `--time-zone` (string) - Interpret all calendar specs in 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 a Search Attribute for the schedule in `KEY=VALUE` format. `KEY` must be a string identifier (no quotes) and `VALUE` must be a JSON value. May be passed multiple times to set multiple Search Attributes. +* `--schedule-memo` (string[]) - Set a memo for the schedule in `KEY=VALUE` format. `KEY` must be a string identifier (no quotes) and `VALUE` must be a JSON value. May be passed multiple times to set multiple memo values. #### Options @@ -490,7 +504,7 @@ 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: Delete a Schedule The `temporal schedule delete` command deletes a Schedule. Deleting a Schedule does not affect any Workflows started by the Schedule. @@ -502,7 +516,7 @@ workflow delete` with the `TemporalScheduledById` Search Attribute. Includes options set for [schedule-id](#options-set-for-schedule-id). -### temporal schedule describe: Get Schedule configuration and current state. +### temporal schedule describe: Get Schedule configuration and current state The `temporal schedule describe` command shows the current configuration of one Schedule, including information about past, current, and future Workflow Runs. @@ -511,16 +525,16 @@ including information about past, current, and future Workflow Runs. Includes options set for [schedule-id](#options-set-for-schedule-id). -### temporal schedule list: Lists Schedules. +### temporal schedule list: List all Schedules The `temporal schedule list` command lists all Schedules in a namespace. #### 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) - Emit detailed information. +* `--really-long` (bool) - Emit even more detailed information that's not usable in table form. -### temporal schedule toggle: Pauses or unpauses a Schedule. +### temporal schedule toggle: Pause or unpause a Schedule The `temporal schedule toggle` command can pause and unpause a Schedule. @@ -536,18 +550,18 @@ Examples: * `--pause` (bool) - Pauses the schedule. * `--reason` (string) - Reason for pausing/unpausing. Default: "(no reason provided)". -* `--unpause` (bool) - Pauses the schedule. +* `--unpause` (bool) - Unpauses 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: Trigger a schedule to run immediately #### 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 a Schedule with a new definition The temporal schedule update command updates an existing Schedule. It replaces the entire configuration of the schedule, including spec, action, and policies. @@ -560,13 +574,13 @@ 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): `temporal server start-dev` -### temporal server start-dev: Start Temporal development server. +### temporal server start-dev: Start Temporal development server Start [Temporal Server](/concepts/what-is-the-temporal-server) on `localhost:7233` with: @@ -597,7 +611,7 @@ To persist Workflows across runs, use: * `--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. -### temporal task-queue: Manage Task Queues. +### temporal task-queue: Manage Task Queues 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]`. @@ -606,7 +620,7 @@ Queue command, run `temporal task-queue [command] [command options]`. Includes options set for [client](#options-set-for-client). -### temporal task-queue describe: Provides information for Workers that have recently polled on this Task Queue. +### temporal task-queue describe: Show Workers that have recently polled on a Task Queue The `temporal task-queue describe` command provides [poller](/application-development/worker-performance#poller-count) information for a given [Task Queue](/concepts/what-is-a-task-queue). @@ -628,7 +642,7 @@ Use the options listed below to modify what this command returns. * `--task-queue-type` (string-enum) - Task Queue type. Options: workflow, activity. Default: workflow. * `--partitions` (int) - Query for all partitions up to this number (experimental+temporary feature). Default: 1. -### temporal task-queue get-build-id-reachability: Retrieves information about the reachability of Build IDs on one or more Task Queues. +### temporal task-queue get-build-id-reachability: Show which Build IDs are available on a Task Queue 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. @@ -638,7 +652,7 @@ This command can tell you whether or not Build IDs may be used for new, existing * `--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. -### temporal task-queue get-build-ids: Fetch the sets of worker Build ID versions on the Task Queue. +### temporal task-queue get-build-ids: Show worker Build ID versions on a Task Queue Fetch the sets of compatible build IDs associated with a Task Queue and associated information. @@ -647,7 +661,7 @@ Fetch the sets of compatible build IDs associated with a Task Queue and associat * `--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. -### temporal task-queue list-partition: Lists the Task Queue's partitions and the matching nodes they are assigned to. +### temporal task-queue list-partition: List a Task Queue's partitions The temporal task-queue list-partition command displays the partitions of a Task Queue, along with the matching node they are assigned to. @@ -655,11 +669,11 @@ The temporal task-queue list-partition command displays the partitions of a Task * `--task-queue`, `-t` (string) - Task queue name. Required. -### temporal task-queue update-build-ids: Operations to update the sets of worker Build ID versions on the Task Queue. +### temporal task-queue update-build-ids: Operations to manage Build ID versions on a Task Queue 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: Add a new build ID compatible with an existing ID to the Task Queue version sets. +### temporal task-queue update-build-ids add-new-compatible: Add a new build ID compatible with an existing ID to a Task Queue's version sets The new build ID will become the default for the set containing the existing ID. See per-flag help for more. @@ -670,7 +684,7 @@ The new build ID will become the default for the set containing the existing ID. * `--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. -### 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: Add a new default (incompatible) build ID to a Task Queue's version sets 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. @@ -679,7 +693,7 @@ Creates a new build id set which will become the new overall default for the que * `--build-id` (string) - The new build id to be added. Required. * `--task-queue`, `-t` (string) - Name of the Task Queue. Required. -### 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: Promote a build ID to become the default for its containing set New tasks compatible with the set will be dispatched to the default id. @@ -688,7 +702,7 @@ New tasks compatible with the set will be dispatched to the default id. * `--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. -### 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: Promote a build ID set to become the default for a Task Queue If the set is already the default, this command has no effect. @@ -698,7 +712,7 @@ If the set is already the default, this command has no effect. * `--task-queue`, `-t` (string) - Name of the Task Queue. Required. -### 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). @@ -724,7 +738,7 @@ Workflow commands use this syntax: `temporal workflow COMMAND [ARGS]`. * `--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 cancel: Cancel a Workflow Execution. +### temporal workflow cancel: Cancel a Workflow Execution 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 @@ -746,7 +760,7 @@ Use the options listed below to change the behavior of this command. Includes options set for [single workflow or batch](#options-set-single-workflow-or-batch) -### temporal workflow count: Count Workflow Executions. +### temporal workflow count: Count Workflow Executions The `temporal workflow count` command returns a count of [Workflow Executions](/concepts/what-is-a-workflow-execution). @@ -756,7 +770,7 @@ Use the options listed below to change the command's behavior. * `--query`, `-q` (string) - Filter results using a SQL-like query. -### temporal workflow delete: Deletes a Workflow Execution. +### temporal workflow delete: Delete a 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). @@ -773,7 +787,7 @@ Use the options listed below to change the command's behavior. Includes options set for [single workflow or batch](#options-set-single-workflow-or-batch) -### temporal workflow describe: Show information about a Workflow Execution. +### temporal workflow describe: Show information about a Workflow Execution The `temporal workflow describe` command shows information about a given [Workflow Execution](/concepts/what-is-a-workflow-execution). @@ -798,7 +812,7 @@ Use the command options below to change the information returned by this command * `--reset-points` (bool) - Only show auto-reset points. * `--raw` (bool) - Print properties without changing their format. -### temporal workflow execute: Start a new Workflow Execution and prints its progress. +### temporal workflow execute: Start a new Workflow Execution and prints its progress 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. @@ -823,7 +837,7 @@ Includes options set for [shared workflow start](#options-set-for-shared-workflo 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 to the current format ``` temporal workflow fix-history-json \ @@ -838,7 +852,7 @@ Use the options listed below to change the command's behavior. * `--source`, `-s` (string) - Path to the input file. Required. * `--target`, `-t` (string) - Path to the output file, or standard output if not set. -### temporal workflow list: List Workflow Executions based on a Query. +### temporal workflow list: List Workflow Executions based on a Query 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). @@ -858,7 +872,7 @@ Use the command options below to change the information returned by this command * `--archived` (bool) - If set, will only query and list archived workflows instead of regular workflows. * `--limit` (int) - Limit the number of items to print. -### temporal workflow query: Query a Workflow Execution. +### temporal workflow query: Query a Workflow Execution The `temporal workflow query` command is used to [Query](/concepts/what-is-a-query) a [Workflow Execution](/concepts/what-is-a-workflow-execution) @@ -882,7 +896,7 @@ Use the options listed below to change the command's behavior. 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: Reset a Workflow Execution to an older point in history 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). @@ -910,11 +924,11 @@ Use the options listed below to change reset behavior. * `--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. +* `--yes`, `-y` (bool) - Don't ask for confirmation. (Note: Only allowed if --query is present) -### temporal workflow show: Show Event History for a Workflow Execution. +### 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 @@ -929,7 +943,7 @@ Use the options listed below to change the command's behavior. Includes options set for [workflow reference](#options-set-for-workflow-reference). -### temporal workflow signal: Signal Workflow Execution by Id. +### temporal workflow signal: Signal 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). @@ -951,15 +965,14 @@ 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. +* `--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 --query 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. +* `--yes`, `-y` (bool) - Don't ask for confirmation. (Note: Only allowed if --query is present) -### temporal workflow stack: Query a Workflow Execution for its stack trace. +### temporal workflow stack: Show the stack trace of a Workflow Execution 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. @@ -979,7 +992,7 @@ Use the options listed below to change the command's behavior. Includes options set for [workflow reference](#options-set-for-workflow-reference). -### temporal workflow start: Starts a new Workflow Execution. +### temporal workflow start: Start a new 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). @@ -994,35 +1007,35 @@ temporal workflow start \ #### Options set for shared workflow start: -* `--workflow-id`, `-w` (string) - Workflow Id. +* `--workflow-id`, `-w` (string) - Workflow Id * `--type` (string) - Workflow Type name. Required. * `--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. +* `--run-timeout` (duration) - Fail a Workflow Run if it takes longer than `DURATION`. +* `--execution-timeout` (duration) - Fail a WorkflowExecution if it takes longer than `DURATION`, including retries and ContinueAsNew tasks. +* `--task-timeout` (duration) - Fail a Workflow Task if it takes longer than `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. #### 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: +* `--cron` (string) - Cron schedule for the Workflow. Deprecated - use schedules instead. +* `--fail-existing` (bool) - Fail if the Workflow already exists. +* `--start-delay` (duration) - Wait before starting the Workflow. Cannot be used with a cron schedule. If the + Workflow receives a signal or update before the delay has elapsed, it will start immediately. +* `--id-reuse-policy` (string) - Allow the same Workflow Id to be used in a new Workflow Execution. 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. +* `--input`, `-i` (string[]) - Input value (default JSON unless --input-meta is non-JSON encoding). Can + be passed multiple times for multiple arguments. Cannot be combined with --input-file. +* `--input-file` (string[]) - Read `PATH` as the input value (JSON by default unless --input-meta is non-JSON + encoding). Can be passed multiple times for multiple arguments. Cannot be combined with --input. +* `--input-meta` (string[]) - Metadata for the input payload, specified as a `KEY=VALUE` pair. If KEY is "encoding", overrides the + default of "json/plain". Pass multiple --input-meta options to set multiple pairs. +* `--input-base64` (bool) - Assume inputs are base64-encoded and attempt to decode them. -### temporal workflow terminate: Terminate Workflow Execution by ID or List Filter. +### temporal workflow terminate: Terminate a Workflow Execution 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 @@ -1045,28 +1058,28 @@ Use the options listed below to change the behavior of this command. * `--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 +* `--query`, `-q` (string) - Start a batch to terminate Workflow Executions with the `QUERY` 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. -### temporal workflow trace: Terminate Workflow Execution by ID or List Filter. +### temporal workflow trace: Interactively show the progress of a Workflow Execution -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. +The `temporal workflow trace` command displays the progress of a [Workflow Execution](/concepts/what-is-a-workflow-execution) and its child workflows with a real-time trace. This view provides a great way to understand the flow of a workflow. Use the options listed below to change the behavior of this command. #### 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 Child Workflows with the specified `STATUS`. To specify multiple statuses, pass --fold multiple times. This will reduce the amount of information fetched and displayed. Case-insensitive. 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) - Fetch up to N Child Workflows deep. Use -1 to fetch child workflows at any depth. Default: -1. +* `--concurrency` (int) - Fetch up to N Workflow Histories 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: Update a running workflow synchronously 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). @@ -1083,10 +1096,10 @@ Use the options listed below to change the command's behavior. #### Options * `--name` (string) - Update Name. Required. -* `--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. +* `--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. + with `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 b11c4ff5..d6bcbf16 100644 --- a/temporalcli/commandsmd/parse.go +++ b/temporalcli/commandsmd/parse.go @@ -256,9 +256,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 From 3ff8fb07c4c223a6429e200e45951404751ec175 Mon Sep 17 00:00:00 2001 From: Erica Sadun Date: Mon, 13 May 2024 17:29:37 -0600 Subject: [PATCH 02/52] EDU-2415: Updates contributor instructions Also: * Adds language for `temporal`, `temporal activity`, `temporal activity complete` and `temporal activity fail`. NOTES * I'm a little confused by the inconsistency of punctuation. * How wordy do you want the command-line usage to be? There's already an overwhelming amount of "wall of text". I was thinking more: ``` * `--env` (string) - Active environment name. Default: default. Env: TEMPORAL_ENV. * `--env-file` (string) - Path to environment settings file (defaults to `$HOME/.config/temporalio/temporal.yaml`). * `--log-level` (string-enum) - Log level. Default is "info" for most commands and "warn" for `server start-dev`. Options: debug, info, warn, error, never. Default: info. * `--log-format` (string) - Log format. Options are "text" and "json". Default is "text". * `--output`, `-o` (string-enum) - Non-logging data output format. Options: text, json, jsonl, none. Default: text. * `--time-format` (string-enum) - Time format. Options: relative, iso, raw. Default: relative. * `--color` (string-enum) - Output coloring. Options: always, never, auto. Default: auto. * `--no-json-shorthand-payloads` (bool) - Show all payloads as raw, even if they are JSON. Default: false. ``` over ``` * `--env` (string) - Read additional options from the `ENV` environment. (See "temporal env --help" for more about environments.) Default: default. Env: TEMPORAL_ENV. * `--env-file` (string) - Read/store per-environment configuration in `PATH` (defaults to "$HOME/.config/temporalio/temporal.yaml"). * `--log-level` (string-enum) - Log level. Default is "info" for most commands and "warn" for the development server. Options: debug, info, warn, error, never. Default: info. * `--log-format` (string) - Emit log messages in "text" or "json" format. Default is "text". * `--output`, `-o` (string-enum) - Emit output in the `FMT` format. Does not affect logs; use --log-format instead. Options: text, json, jsonl, none. Default: text. * `--time-format` (string-enum) - Emit timestamps in the `FMT` format. Options: relative, iso, raw. Default: relative. * `--color` (string-enum) - Colorize output. Does not affect logs. Options: always, never, auto. Default: auto. * `--no-json-shorthand-payloads` (bool) - Show all payloads as raw payloads even if they are JSON. ``` ISSUES 1. There's no way to bundle the `temporal` options, which are imported elsewhere. They have to be there and they are distracting, and contribute to overwhelmed users. 2. Even though I set a description for complete and fail, they are not shown cli% ./temporal activity complete Error: required flag(s) "activity-id", "result", "workflow-id" not set Usage: temporal activity complete [flags] Ditto for temporal activity fail. --- Makefile | 14 ++ temporalcli/commands.gen.go | 12 +- temporalcli/commandsmd/commands.md | 197 +++++++++++++++++++++-------- 3 files changed, 161 insertions(+), 62 deletions(-) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..e68f6f8a --- /dev/null +++ b/Makefile @@ -0,0 +1,14 @@ +.PHONY: all gen build edit + +all: gen build + +gen: + @echo "Generating" + go run ./temporalcli/internal/cmd/gen-commands + +build: + @echo "Building" + go build ./cmd/temporal + +edit: + open temporalcli/commandsmd/commands.md diff --git a/temporalcli/commands.gen.go b/temporalcli/commands.gen.go index fecd6eaa..de11f5e7 100644 --- a/temporalcli/commands.gen.go +++ b/temporalcli/commands.gen.go @@ -32,7 +32,7 @@ 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.Long = "The Temporal CLI (Command Line Interface) is a powerful tool for managing, \nmonitoring, and debugging Temporal Applications. It provides developers with \ndirect access to a Temporal Service from their terminal. With the Temporal CLI,\ndevelopers can start their applications, pass messages, cancel application\nsteps, and more." s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalActivityCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalBatchCommand(cctx, &s).Command) @@ -70,7 +70,7 @@ func NewTemporalActivityCommand(cctx *CommandContext, parent *TemporalCommand) * s.Parent = parent s.Command.Use = "activity" s.Command.Short = "Complete or fail an Activity" - s.Command.Long = "" + s.Command.Long = "Update an Activity to report that it has completed or failed. This process\nmarks an activity as successfully finished or as having encountered an error\nduring execution." s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalActivityCompleteCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalActivityFailCommand(cctx, &s).Command) @@ -94,9 +94,9 @@ func NewTemporalActivityCompleteCommand(cctx *CommandContext, parent *TemporalAc s.Command.Use = "complete [flags]" 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.\n\n\x1b[1mtemporal activity complete --activity-id=MyActivityId --workflow-id=MyWorkflowId --result='{\"MyResultKey\": \"MyResultVal\"}'\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.\n\n`temporal activity complete --activity-id=MyActivityId --workflow-id=MyWorkflowId --result='{\"MyResultKey\": \"MyResultVal\"}'`" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) @@ -130,9 +130,9 @@ func NewTemporalActivityFailCommand(cctx *CommandContext, parent *TemporalActivi s.Command.Use = "fail [flags]" 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 during execution.\n\n\x1b[1mtemporal activity fail --activity-id=MyActivityId --workflow-id=MyWorkflowId\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 during execution.\n\n`temporal activity fail --activity-id=MyActivityId --workflow-id=MyWorkflowId`" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) diff --git a/temporalcli/commandsmd/commands.md b/temporalcli/commandsmd/commands.md index 2cc48cd4..1fe40172 100644 --- a/temporalcli/commandsmd/commands.md +++ b/temporalcli/commandsmd/commands.md @@ -4,71 +4,152 @@ Commands for the Temporal CLI. ### temporal: Temporal command-line interface and development server +The Temporal CLI (Command Line Interface) is a powerful tool for managing, +monitoring, and debugging Temporal Applications. It provides developers with +direct access to a Temporal Service from their terminal. With the Temporal CLI, +developers can start their applications, pass messages, cancel application +steps, and more. + @@ -88,6 +169,10 @@ Examples showing correct/incorrect usage text for the optional `--history-uri` f ### temporal activity: Complete or fail an Activity +Update an Activity to report that it has completed or failed. This process +marks an activity as successfully finished or as having encountered an error +during execution. + #### Options Includes options set for [client](#options-set-for-client). @@ -95,7 +180,7 @@ Includes options set for [client](#options-set-for-client). ### temporal activity complete: Complete an Activity -Complete an Activity. +Complete an Activity, marking it as successfully finished. `temporal activity complete --activity-id=MyActivityId --workflow-id=MyWorkflowId --result='{"MyResultKey": "MyResultVal"}'` @@ -109,7 +194,7 @@ Includes options set for [workflow reference](#options-set-for-workflow-referenc ### temporal activity fail: Fail an Activity -Fail an Activity. +Fail an Activity, marking it as having encountered an error during execution. `temporal activity fail --activity-id=MyActivityId --workflow-id=MyWorkflowId` From 080a46516518a95f8c7a537749ed2a06acd15560 Mon Sep 17 00:00:00 2001 From: Erica Sadun Date: Tue, 14 May 2024 09:39:35 -0600 Subject: [PATCH 03/52] EDU-2415 Tues Morning 14 May Proof of concept material is pretty much there before I move forward. --- Makefile | 7 +- temporalcli/commands.gen.go | 118 +++++++------- temporalcli/commandsmd/commands.md | 245 +++++++++++++++++++++-------- 3 files changed, 247 insertions(+), 123 deletions(-) diff --git a/Makefile b/Makefile index e68f6f8a..905b4a1c 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: all gen build edit +.PHONY: all gen build edit open all: gen build @@ -11,4 +11,7 @@ build: go build ./cmd/temporal edit: - open temporalcli/commandsmd/commands.md + open ./temporalcli/commandsmd/commands.md + +open: + open ./temporalcli/commandsmd/commands.md diff --git a/temporalcli/commands.gen.go b/temporalcli/commands.gen.go index de11f5e7..8a33d057 100644 --- a/temporalcli/commands.gen.go +++ b/temporalcli/commands.gen.go @@ -32,7 +32,11 @@ 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 = "The Temporal CLI (Command Line Interface) is a powerful tool for managing, \nmonitoring, and debugging Temporal Applications. It provides developers with \ndirect access to a Temporal Service from their terminal. With the Temporal CLI,\ndevelopers can start their applications, pass messages, cancel application\nsteps, and more." + if hasHighlighting { + s.Command.Long = "The Temporal CLI (Command Line Interface) provide a powerful tool to manage, \nmonitor, and debug your Temporal applications. It also lets you run a local\nTemporal Service directly from your terminal. With this CLI, you can \nstart Workflows, pass messages, cancel application steps, and more.\n\n* Start a local development service: \n \x1b[1mtemporal server start-dev\x1b[0m \n* Help messages: pass --help for any command\n \x1b[1mtemporal activity complete --help\x1b[0m\n\nRead more: https://docs.temporal.io/cli" + } else { + s.Command.Long = "The Temporal CLI (Command Line Interface) provide a powerful tool to manage, \nmonitor, and debug your Temporal applications. It also lets you run a local\nTemporal Service directly from your terminal. With this CLI, you can \nstart Workflows, pass messages, cancel application steps, and more.\n\n* Start a local development service: \n `temporal server start-dev` \n* Help messages: pass --help for any command\n `temporal activity complete --help`\n\nRead more: https://docs.temporal.io/cli" + } 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", "", "Read additional options from the `ENV` environment. (See \"temporal env --help\" for more about environments.) Default: default.") + s.Command.PersistentFlags().StringVar(&s.Env, "env", "default", "Active environment name.") cctx.BindFlagEnvVar(s.Command.PersistentFlags().Lookup("env"), "TEMPORAL_ENV") - s.Command.PersistentFlags().StringVar(&s.EnvFile, "env-file", "", "Read/store per-environment configuration in `PATH` (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 the development server. Accepted values: debug, info, warn, error, never.") - s.Command.PersistentFlags().StringVar(&s.LogFormat, "log-format", "", "Emit log messages in \"text\" or \"json\" format. Default is \"text\".") + 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.Output = NewStringEnum([]string{"text", "json", "jsonl", "none"}, "text") - s.Command.PersistentFlags().VarP(&s.Output, "output", "o", "Emit output in the `FMT` format. Does not affect logs; use --log-format instead. 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", "Emit timestamps in the `FMT` format. Accepted values: relative, iso, raw.") + 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", "Colorize output. Does not affect logs. Accepted values: always, never, auto.") - s.Command.PersistentFlags().BoolVar(&s.NoJsonShorthandPayloads, "no-json-shorthand-payloads", false, "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, "Show all payloads as raw, even if they are JSON.") s.initCommand(cctx) return &s } @@ -70,7 +74,7 @@ func NewTemporalActivityCommand(cctx *CommandContext, parent *TemporalCommand) * s.Parent = parent s.Command.Use = "activity" s.Command.Short = "Complete or fail an Activity" - s.Command.Long = "Update an Activity to report that it has completed or failed. This process\nmarks an activity as successfully finished or as having encountered an error\nduring execution." + s.Command.Long = "Update an Activity to report that it has completed or failed. This process\nmarks an activity as successfully finished or as having encountered an error\nduring execution.\n\nRead more: https://docs.temporal.io/cli/activity" s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalActivityCompleteCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalActivityFailCommand(cctx, &s).Command) @@ -94,15 +98,15 @@ func NewTemporalActivityCompleteCommand(cctx *CommandContext, parent *TemporalAc s.Command.Use = "complete [flags]" s.Command.Short = "Complete an Activity" if hasHighlighting { - s.Command.Long = "Complete an Activity, marking it as successfully finished.\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 \nthe ID and include a JSON result to use for the returned value.\n\n\x1b[1mtemporal activity complete \\\n --activity-id=YourActivityId \\\n --workflow-id=YourWorkflowId \\\n --result='{\"YourResultKey\": \"YourResultVal\"}'\x1b[0m\n\nRead more: https://docs.temporal.io/cli/activity#complete" } else { - s.Command.Long = "Complete an Activity, marking it as successfully finished.\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 \nthe ID and include a JSON result to use for the returned value.\n\n```\ntemporal activity complete \\\n --activity-id=YourActivityId \\\n --workflow-id=YourWorkflowId \\\n --result='{\"YourResultKey\": \"YourResultVal\"}'\n```\n\nRead more: https://docs.temporal.io/cli/activity#complete" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) - s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "`ID` of the Activity to be completed.") + s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "Activity `ID` to complete.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "activity-id") - s.Command.Flags().StringVar(&s.Result, "result", "", "Result `JSON` with which to complete the Activity.") + s.Command.Flags().StringVar(&s.Result, "result", "", "Result `JSON` for completing the Activity.") _ = 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) { @@ -130,9 +134,9 @@ func NewTemporalActivityFailCommand(cctx *CommandContext, parent *TemporalActivi s.Command.Use = "fail [flags]" s.Command.Short = "Fail an Activity" if hasHighlighting { - s.Command.Long = "Fail an Activity, marking it as having encountered an error during execution.\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 during execution.\nSpecify the Activity and Workflow Ids.\n\n\x1b[1mtemporal activity fail \\\n --activity-id=YourActivityId \\\n --workflow-id=YourWorkflowId\x1b[0m\n\nRead more: https://docs.temporal.io/cli/activity#fail" } else { - s.Command.Long = "Fail an Activity, marking it as having encountered an error during execution.\n\n`temporal activity fail --activity-id=MyActivityId --workflow-id=MyWorkflowId`" + s.Command.Long = "Fail an Activity, marking it as having encountered an error during execution.\nSpecify the Activity and Workflow Ids.\n\n```\ntemporal activity fail \\\n --activity-id=YourActivityId \\\n --workflow-id=YourWorkflowId\n```\n\nRead more: https://docs.temporal.io/cli/activity#fail" } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) @@ -160,7 +164,11 @@ func NewTemporalBatchCommand(cctx *CommandContext, parent *TemporalCommand) *Tem s.Parent = parent s.Command.Use = "batch" s.Command.Short = "Manage Batch Jobs" - s.Command.Long = "Batch commands change multiple Workflow Executions at once." + if hasHighlighting { + s.Command.Long = "A batch job will execute a single command affecting multiple Workflow \nExecutions in tandem. These commands include:\n\n* Cancel: Cancel the Workflow Executions specified by the List Filter.\n* Signal: Signal the Workflow Executions specified by the List Filter.\n* Terminate: Terminates the Workflow Executions specified by the List Filter.\n\nYou specify which Workflow Executions to include and the kind of batch \njob to apply. For example, cancel all the running 'YourWorkflow' Workflows:\n\n\x1b[1mtemporal workflow cancel \\\n --query 'ExecutionStatus = \"Running\" AND WorkflowType=\"YourWorkflow\"' \\\n --reason \"Testing\"\x1b[0m\n\nRead more: https://docs.temporal.io/cli/batch" + } else { + s.Command.Long = "A batch job will execute a single command affecting multiple Workflow \nExecutions in tandem. These commands include:\n\n* Cancel: Cancel the Workflow Executions specified by the List Filter.\n* Signal: Signal the Workflow Executions specified by the List Filter.\n* Terminate: Terminates the Workflow Executions specified by the List Filter.\n\nYou specify which Workflow Executions to include and the kind of batch \njob to apply. For example, cancel all the running 'YourWorkflow' Workflows:\n\n```\ntemporal workflow cancel \\\n --query 'ExecutionStatus = \"Running\" AND WorkflowType=\"YourWorkflow\"' \\\n --reason \"Testing\"\n ```\n\nRead more: https://docs.temporal.io/cli/batch" + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalBatchDescribeCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalBatchListCommand(cctx, &s).Command) @@ -182,9 +190,9 @@ func NewTemporalBatchDescribeCommand(cctx *CommandContext, parent *TemporalBatch s.Command.Use = "describe [flags]" s.Command.Short = "Show Batch Job progress" if hasHighlighting { - s.Command.Long = "Show 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\nto return the job's information:\n\n\x1b[1mtemporal batch describe --job-id=YourJobId\x1b[0m\n\nRead more: https://docs.temporal.io/cli/batch" } else { - s.Command.Long = "Show 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\nto return the job's information:\n\n```\ntemporal batch describe --job-id=YourJobId\n```\n\nRead more: https://docs.temporal.io/cli/batch" } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.JobId, "job-id", "", "The Batch Job Id to describe.") @@ -210,9 +218,9 @@ func NewTemporalBatchListCommand(cctx *CommandContext, parent *TemporalBatchComm s.Command.Use = "list [flags]" s.Command.Short = "List all Batch Jobs" if hasHighlighting { - s.Command.Long = "List all Batch Jobs. Batch 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, for the entire Service or a single Namespace.\n\n\x1b[1mtemporal batch list --namespace=YourNamespace\x1b[0m\n\nRead more: https://docs.temporal.io/cli/batch#list" } else { - s.Command.Long = "List all Batch Jobs. Batch 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, for the entire Service or a single Namespace.\n\n```\ntemporal batch list --namespace=YourNamespace\n```\n\nRead more: https://docs.temporal.io/cli/batch#list" } s.Command.Args = cobra.NoArgs s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Show only the first `N` Batch Jobs in the list.") @@ -238,9 +246,9 @@ func NewTemporalBatchTerminateCommand(cctx *CommandContext, parent *TemporalBatc s.Command.Use = "terminate [flags]" s.Command.Short = "Terminate a Batch Job" if hasHighlighting { - s.Command.Long = "The temporal batch terminate command terminates a Batch Job with the provided Job Id.\nYou must provide a reason for terminating the Batch Job, which is stored for future reference.\n\n\x1b[1mtemporal batch terminate --job-id=MyJobId --reason=JobReason\x1b[0m" + s.Command.Long = "Terminate the Batch job with the provided Job Id. You must provide\na reason motivating the termination, which is stored with the Service\nfor later reference.\n\n\x1b[1mtemporal batch terminate --job-id=YourJobId --reason=YourTerminationReason\x1b[0m\n\nRead more: https://docs.temporal.io/cli/batch#terminate" } else { - s.Command.Long = "The temporal batch terminate command terminates a Batch Job with the provided Job Id.\nYou must provide a reason for terminating the Batch Job, which is stored for future reference.\n\n`temporal batch terminate --job-id=MyJobId --reason=JobReason`" + s.Command.Long = "Terminate the Batch job with the provided Job Id. You must provide\na reason motivating the termination, which is stored with the Service\nfor later reference.\n\n```\ntemporal batch terminate --job-id=YourJobId --reason=YourTerminationReason\n```\n\nRead more: https://docs.temporal.io/cli/batch#terminate" } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.JobId, "job-id", "", "The Batch Job Id to terminate.") @@ -266,9 +274,9 @@ func NewTemporalEnvCommand(cctx *CommandContext, parent *TemporalCommand) *Tempo s.Command.Use = "env" s.Command.Short = "Manage environments" if hasHighlighting { - s.Command.Long = "Environments allow you to specify named sets of flags to apply by default. Most commonly, environments are used to override the \x1b[1m--address\x1b[0m flag to point to different Temporal Server instances (for example, having different \"dev\" and \"prod\" environments).\n\nUse the \x1b[1m--env\x1b[0m option with any \x1b[1mtemporal\x1b[0m command to choose the environment. You can also specify the environment using the \x1b[1mTEMPORAL_ENV\x1b[0m environment variable. If no environment is specified, the 'default' environment is used." + s.Command.Long = "Environments enable you to create and manage named option presets \nto automate command configuration. It provides easy set-up for separate \n\"dev\" and \"prod\" environments. \n\nFor example, you might set an endpoint preset that overrides the\n\x1b[1m--address\x1b[0m option. This enables you to select distinct Temporal Services \nand Namespaces for your commands.\n\nEnvironments are named, for example \"prod\". Each environment stores a \nlist of key-value pairs, as you see here:\n\n\x1b[1mtemporal env set prod.namespace production.f45a2 \ntemporal env set prod.address production.f45a2.tmprl.cloud:7233 \ntemporal env set prod.tls-cert-path /temporal/certs/prod.pem \ntemporal env set prod.tls-key-path /temporal/certs/prod.key\x1b[0m\n\nCheck your presets with \x1b[1mtemporal env get prod\x1b[0m:\n\n\x1b[1maddress production.f45a2.tmprl.cloud:7233 \nnamespace production.f45a2 \ntls-cert-path /temporal/certs/prod.pem \ntls-key-path /temporal/certs/prod.key\x1b[0m\n\nTo use the environment with a command, pass \x1b[1m--env\x1b[0m followed by the\nenvironment name. For example, to list workflows in the \"prod\" environment:\n\n\x1b[1m$ temporal workflow list --env prod\x1b[0m\n\nYou specify an active environment using the \x1b[1mTEMPORAL_ENV\x1b[0m environment variable. If no environment is specified, the 'default' environment is used.\n\nRead more: https://docs.temporal.io/cli/env" } else { - s.Command.Long = "Environments allow you to specify named sets of flags to apply by default. Most commonly, environments are used to override the `--address` flag to point to different Temporal Server instances (for example, having different \"dev\" and \"prod\" environments).\n\nUse the `--env` option with any `temporal` command to choose the environment. You can also specify the environment using the `TEMPORAL_ENV` environment variable. If no environment is specified, the 'default' environment is used." + s.Command.Long = "Environments enable you to create and manage named option presets \nto automate command configuration. It provides easy set-up for separate \n\"dev\" and \"prod\" environments. \n\nFor example, you might set an endpoint preset that overrides the\n`--address` option. This enables you to select distinct Temporal Services \nand Namespaces for your commands.\n\nEnvironments are named, for example \"prod\". Each environment stores a \nlist of key-value pairs, as you see here:\n\n```\ntemporal env set prod.namespace production.f45a2 \ntemporal env set prod.address production.f45a2.tmprl.cloud:7233 \ntemporal env set prod.tls-cert-path /temporal/certs/prod.pem \ntemporal env set prod.tls-key-path /temporal/certs/prod.key\n```\n\nCheck your presets with `temporal env get prod`:\n\n``` \naddress production.f45a2.tmprl.cloud:7233 \nnamespace production.f45a2 \ntls-cert-path /temporal/certs/prod.pem \ntls-key-path /temporal/certs/prod.key\n```\n\nTo use the environment with a command, pass `--env` followed by the\nenvironment name. For example, to list workflows in the \"prod\" environment:\n\n```\n$ temporal workflow list --env prod\n```\n\nYou specify an active environment using the `TEMPORAL_ENV` environment variable. If no environment is specified, the 'default' environment is used.\n\nRead more: https://docs.temporal.io/cli/env" } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalEnvDeleteCommand(cctx, &s).Command) @@ -291,9 +299,9 @@ func NewTemporalEnvDeleteCommand(cctx *CommandContext, parent *TemporalEnvComman s.Command.Use = "delete [flags]" 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 an environment or a key-value pair within that environment:\n\n\x1b[1mtemporal env delete [environment or property]\x1b[0m\n\nFor example:\n\n\x1b[1mtemporal env delete --env prod\ntemporal env delete --env prod --key tls-cert-path\x1b[0m\n\nIf you don't specify an environment, you delete the \x1b[1mdefault\x1b[0m environment:\n\n\x1b[1mtemporal env delete --key tls-cert-path\x1b[0m\n\nRead more: https://docs.temporal.io/cli/env#delete" } 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 an environment or a key-value pair within that environment:\n\n```\ntemporal env delete [environment or property]\n```\n\nFor example:\n\n```\ntemporal env delete --env prod\ntemporal env delete --env prod --key tls-cert-path\n```\n\nIf you don't specify an environment, you delete the `default` environment:\n\n```\ntemporal env delete --key tls-cert-path\n```\n\nRead more: https://docs.temporal.io/cli/env#delete" } s.Command.Args = cobra.MaximumNArgs(1) s.Command.Flags().StringVarP(&s.Key, "key", "k", "", "The name of the property") @@ -318,9 +326,9 @@ func NewTemporalEnvGetCommand(cctx *CommandContext, parent *TemporalEnvCommand) s.Command.Use = "get [flags]" s.Command.Short = "Print 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 = "\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 --key 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." } 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 = "`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 --key 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.Args = cobra.MaximumNArgs(1) s.Command.Flags().StringVarP(&s.Key, "key", "k", "", "The name of the property") @@ -616,9 +624,9 @@ func NewTemporalOperatorNamespaceCreateCommand(cctx *CommandContext, parent *Tem s.Command.Use = "create [flags]" 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 = "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=YourCluster -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" } 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 = "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=YourCluster -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.Args = cobra.MaximumNArgs(1) s.Command.Flags().StringVar(&s.ActiveCluster, "active-cluster", "", "Active cluster name") @@ -1299,9 +1307,9 @@ func NewTemporalTaskQueueDescribeCommand(cctx *CommandContext, parent *TemporalT s.Command.Use = "describe [flags]" s.Command.Short = "Show Workers that have recently polled on a Task Queue" if hasHighlighting { - s.Command.Long = "The \x1b[1mtemporal task-queue describe\x1b[0m command 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\n\x1b[1mtemporal task-queue describe --task-queue=MyTaskQueue --task-queue-type=\"activity\"\x1b[0m\n\nUse the options listed below to modify what this command returns." + s.Command.Long = "The \x1b[1mtemporal task-queue describe\x1b[0m command 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\n\x1b[1mtemporal task-queue describe --task-queue=YourTaskQueue --task-queue-type=\"activity\"\x1b[0m\n\nUse the options listed below to modify what this command returns." } else { - s.Command.Long = "The `temporal task-queue describe` command 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\n`temporal task-queue describe --task-queue=MyTaskQueue --task-queue-type=\"activity\"`\n\nUse the options listed below to modify what this command returns." + s.Command.Long = "The `temporal task-queue describe` command 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\n`temporal task-queue describe --task-queue=YourTaskQueue --task-queue-type=\"activity\"`\n\nUse the options listed below to modify what this command returns." } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task queue name.") @@ -1627,9 +1635,9 @@ func NewTemporalWorkflowCancelCommand(cctx *CommandContext, parent *TemporalWork s.Command.Use = "cancel [flags]" s.Command.Short = "Cancel a 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 = "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 YourWorkflowId\x1b[0m\n\n...or in bulk via a visibility query list filter:\n\x1b[1mtemporal workflow cancel --query=YourQuery\x1b[0m\n\nUse the options listed below to change the behavior of this command." } 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 = "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 YourWorkflowId\n```\n\n...or in bulk via a visibility query list filter:\n```\ntemporal workflow cancel --query=YourQuery\n```\n\nUse the options listed below to change the behavior of this command." } s.Command.Args = cobra.NoArgs s.SingleWorkflowOrBatchOptions.buildFlags(cctx, s.Command.Flags()) @@ -1681,9 +1689,9 @@ func NewTemporalWorkflowDeleteCommand(cctx *CommandContext, parent *TemporalWork s.Command.Use = "delete [flags]" s.Command.Short = "Delete a 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 = "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 YourWorkflowId \\\x1b[0m\n\nUse the options listed below to change the command's behavior." } 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 = "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 YourWorkflowId \\\n```\n\nUse the options listed below to change the command's behavior." } s.Command.Args = cobra.NoArgs s.SingleWorkflowOrBatchOptions.buildFlags(cctx, s.Command.Flags()) @@ -1753,9 +1761,9 @@ func NewTemporalWorkflowExecuteCommand(cctx *CommandContext, parent *TemporalWor s.Command.Use = "execute [flags]" s.Command.Short = "Start a new Workflow Execution and prints its progress" 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 = "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 YourWorkflow \\\n\t\t--task-queue YourTaskQueue \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\x1b[0m" } 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 = "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 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()) @@ -1815,9 +1823,9 @@ func NewTemporalWorkflowListCommand(cctx *CommandContext, parent *TemporalWorkfl s.Command.Use = "list [flags]" s.Command.Short = "List Workflow Executions based on a Query" 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 = "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=YourQuery\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." } 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 = "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=YourQuery`\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.Args = cobra.NoArgs s.Command.Flags().StringVarP(&s.Query, "query", "q", "", "Filter results using a SQL-like query.") @@ -1847,9 +1855,9 @@ func NewTemporalWorkflowQueryCommand(cctx *CommandContext, parent *TemporalWorkf s.Command.Use = "query [flags]" s.Command.Short = "Query a Workflow Execution" 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 = "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 YourWorkflowId \\\n\t\t--name YourQuery \\\n\t\t--input '{\"YourInputKey\": \"YourInputValue\"}'\x1b[0m\n\nUse the options listed below to change the command's behavior." } 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 = "The `temporal workflow query` command is used to Query a\nWorkflow Execution\nby ID.\n\n```\ntemporal workflow query \\\n\t\t--workflow-id YourWorkflowId \\\n\t\t--name YourQuery \\\n\t\t--input '{\"YourInputKey\": \"YourInputValue\"}'\n```\n\nUse the options listed below to change the command's behavior." } s.Command.Args = cobra.NoArgs s.PayloadInputOptions.buildFlags(cctx, s.Command.Flags()) @@ -1887,9 +1895,9 @@ func NewTemporalWorkflowResetCommand(cctx *CommandContext, parent *TemporalWorkf s.Command.Use = "reset [flags]" s.Command.Short = "Reset a Workflow Execution to an older point in history" 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 = "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=YourLastEvent\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." } 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 = "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=YourLastEvent\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.Args = cobra.NoArgs s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow Id. Required for non-batch reset operations.") @@ -1972,9 +1980,9 @@ func NewTemporalWorkflowSignalCommand(cctx *CommandContext, parent *TemporalWork s.Command.Use = "signal [flags]" s.Command.Short = "Signal 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 = "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 YourWorkflowId \\\n\t\t--name YourSignal \\\n\t\t--input '{\"YourInputKey\": \"YourInputValue\"}'\x1b[0m\n\nUse the options listed below to change the command's behavior." } 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 = "The `temporal workflow signal` command is used to Signal a\nWorkflow Execution by ID.\n\n```\ntemporal workflow signal \\\n\t\t--workflow-id YourWorkflowId \\\n\t\t--name YourSignal \\\n\t\t--input '{\"YourInputKey\": \"YourInputValue\"}'\n```\n\nUse the options listed below to change the command's behavior." } s.Command.Args = cobra.NoArgs s.PayloadInputOptions.buildFlags(cctx, s.Command.Flags()) @@ -2003,9 +2011,9 @@ func NewTemporalWorkflowStackCommand(cctx *CommandContext, parent *TemporalWorkf s.Command.Use = "stack [flags]" s.Command.Short = "Show the stack trace of 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 = "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 YourWorkflowId\x1b[0m\n\nUse the options listed below to change the command's behavior." } 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 = "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 YourWorkflowId\n```\n\nUse the options listed below to change the command's behavior." } s.Command.Args = cobra.NoArgs s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) @@ -2086,9 +2094,9 @@ func NewTemporalWorkflowStartCommand(cctx *CommandContext, parent *TemporalWorkf s.Command.Use = "start [flags]" s.Command.Short = "Start a new 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 = "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 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 = "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 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()) @@ -2119,9 +2127,9 @@ func NewTemporalWorkflowTerminateCommand(cctx *CommandContext, parent *TemporalW s.Command.Use = "terminate [flags]" s.Command.Short = "Terminate 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 = "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 YourWorkflowId\x1b[0m\n\n...or in bulk via a visibility query list filter:\n\x1b[1mtemporal workflow terminate --query=YourQuery\x1b[0m\n\nUse the options listed below to change the behavior of this command." } 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 = "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 YourWorkflowId\n```\n\n...or in bulk via a visibility query list filter:\n```\ntemporal workflow terminate --query=YourQuery\n```\n\nUse the options listed below to change the behavior of this command." } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVarP(&s.WorkflowId, "workflow-id", "w", "", "Workflow Id. Either this or query must be set.") @@ -2190,9 +2198,9 @@ func NewTemporalWorkflowUpdateCommand(cctx *CommandContext, parent *TemporalWork s.Command.Use = "update [flags]" s.Command.Short = "Update a running workflow synchronously" 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 = "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 YourWorkflowId \\\n\t\t--name YourUpdate \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\x1b[0m\n\nUse the options listed below to change the command's behavior." } 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 = "The `temporal workflow update` command is used to synchronously Update a\nWorkflowExecution by ID.\n\n```\ntemporal workflow update \\\n\t\t--workflow-id YourWorkflowId \\\n\t\t--name YourUpdate \\\n\t\t--input '{\"Input\": \"As-JSON\"}'\n```\n\nUse the options listed below to change the command's behavior." } s.Command.Args = cobra.NoArgs s.PayloadInputOptions.buildFlags(cctx, s.Command.Flags()) diff --git a/temporalcli/commandsmd/commands.md b/temporalcli/commandsmd/commands.md index 1fe40172..42edb4bc 100644 --- a/temporalcli/commandsmd/commands.md +++ b/temporalcli/commandsmd/commands.md @@ -144,11 +144,17 @@ OPTION LISTING ### temporal: Temporal command-line interface and development server -The Temporal CLI (Command Line Interface) is a powerful tool for managing, -monitoring, and debugging Temporal Applications. It provides developers with -direct access to a Temporal Service from their terminal. With the Temporal CLI, -developers can start their applications, pass messages, cancel application -steps, and more. +The Temporal CLI (Command Line Interface) provide a powerful tool to manage, +monitor, and debug your Temporal applications. It also lets you run a local +Temporal Service directly from your terminal. With this CLI, you can +start Workflows, pass messages, cancel application steps, and more. + +* Start a local development service: + `temporal server start-dev` +* Help messages: pass --help for any command + `temporal activity complete --help` + +Read more: https://docs.temporal.io/cli ### temporal: Temporal command-line interface and development server -The Temporal CLI (Command Line Interface) provide a powerful tool to manage, +The Temporal CLI (Command Line Interface) provide a powerful tool to manage, monitor, and debug your Temporal applications. It also lets you run a local -Temporal Service directly from your terminal. With this CLI, you can -start Workflows, pass messages, cancel application steps, and more. +Temporal Service directly from your terminal. With this CLI, you can start +Workflows, pass messages, cancel application steps, and more. * Start a local development service: `temporal server start-dev` * Help messages: pass --help for any command: `temporal activity complete --help` -Read more: https://docs.temporal.io/cli - #### Options -* `--env` (string) - Active environment name. Default: default. Env: TEMPORAL_ENV. -* `--env-file` (string) - Path to environment settings file (defaults to `$HOME/.config/temporalio/temporal.yaml`). -* `--log-level` (string-enum) - Log level. Default is "info" for most commands and "warn" for `server start-dev`. - Options: debug, info, warn, error, never. Default: info. -* `--log-format` (string) - Log format. Options are "text" and "json". Default is "text". -* `--output`, `-o` (string-enum) - Non-logging data output format. Options: text, json, jsonl, - none. Default: text. -* `--time-format` (string-enum) - Time format. Options: relative, iso, raw. Default: relative. -* `--color` (string-enum) - Output coloring. Options: always, never, auto. Default: auto. -* `--no-json-shorthand-payloads` (bool) - Raw payload output, even if they are JSON. +* `--env` (string) - Active environment name. + Default: default. + Env: TEMPORAL_ENV. +* `--env-file` (string) - + Path to environment settings file + (defaults to `$HOME/.config/temporalio/temporal.yaml`). +* `--log-level` (string-enum) - Log level. + Default is "info" for most commands and "warn" for `server start-dev`. + Options: debug, info, warn, error, never. Default: info. +* `--log-format` (string) - Log format. + Options are "text" and "json". Default is "text". +* `--output`, `-o` (string-enum) - Non-logging data output format. + Options: text, json, jsonl, none. Default: text. +* `--time-format` (string-enum) - Time format. + Options: relative, iso, raw. Default: relative. +* `--color` (string-enum) - Output coloring. + Options: always, never, auto. Default: auto. +* `--no-json-shorthand-payloads` (bool) - + Raw payload output, even if they are JSON. ### temporal activity: Complete or fail an Activity @@ -186,8 +247,6 @@ Update an Activity to report that it has completed or failed. This process marks an activity as successfully finished or as having encountered an error during execution. -Read more: https://docs.temporal.io/cli/activity - #### Options Includes options set for [client](#options-set-for-client). @@ -204,8 +263,6 @@ temporal activity complete \ --result '{"YourResultKey": "YourResultVal"}' ``` -Read more: https://docs.temporal.io/cli/activity#complete - #### Options * `--activity-id` (string) - Activity `ID` to complete. Required. @@ -225,12 +282,10 @@ temporal activity fail \ --workflow-id YourWorkflowId ``` -Read more: https://docs.temporal.io/cli/activity#fail - #### Options * `--activity-id` (string) - `ID` of the Activity to be failed. Required. -* `--detail` (string) - JSON data describing the reason for failing the Activity +* `--detail` (string) - JSON data with the reason for failing the Activity * `--identity` (string) - Identity of the user submitting this request * `--reason` (string) - Reason for failing the Activity @@ -239,11 +294,7 @@ Includes options set for [workflow reference](#options-set-for-workflow-referenc ### temporal batch: Manage Batch Jobs A batch job executes a single command affecting multiple Workflow -Executions in tandem. Available commands: - -* Cancel: Cancel the Workflow Executions specified by the List Filter. -* Signal: Signal the Workflow Executions specified by the List Filter. -* Terminate: Terminates the Workflow Executions specified by the List Filter. +Executions in tandem. You specify the Workflow Execution You select the Workflow Executions to include and the kind of batch job to apply. For example, cancel all the running 'YourWorkflow' Workflows: @@ -252,9 +303,7 @@ job to apply. For example, cancel all the running 'YourWorkflow' Workflows: temporal workflow cancel \ --query 'ExecutionStatus = "Running" AND WorkflowType="YourWorkflow"' \ --reason "Testing" - ``` - -Read more: https://docs.temporal.io/cli/batch +``` #### Options @@ -269,8 +318,6 @@ to return the job's information: temporal batch describe --job-id YourJobId ``` -Read more: https://docs.temporal.io/cli/batch - #### Options * `--job-id` (string) - The Batch Job Id to describe. Required. @@ -284,8 +331,6 @@ Return a list of Batch jobs, for the entire Service or a single Namespace: temporal batch list --namespace YourNamespace ``` -Read more: https://docs.temporal.io/cli/batch#list - #### Options * `--limit` (int) - Show only the first `N` Batch Jobs in the list. @@ -300,14 +345,13 @@ for later reference. temporal batch terminate --job-id YourJobId --reason YourTerminationReason ``` -Read more: https://docs.temporal.io/cli/batch#terminate - #### Options * `--job-id` (string) - The Batch Job Id to terminate. Required. * `--reason` (string) - Reason for terminating the Batch Job. Required. ### temporal env: Manage environments + Environments help you create and manage grouped key-value presets for Options. They provide easy set-up for separate environments, such as "dev" and "prod" work. @@ -321,10 +365,14 @@ name as part of your assignment, as in this example, which configures the "prod" environment: ``` -temporal env set --env prod --key namespace --value production.f45a2 -temporal env set --env prod --key address --value production.f45a2.tmprl.cloud:7233 -temporal env set --env prod --key tls-cert-path --value /temporal/certs/prod.pem -temporal env set --env prod --key tls-key-path --value /temporal/certs/prod.key +temporal env set --env prod --key namespace \ + --value production.f45a2 +temporal env set --env prod --key address \ + --value production.f45a2.tmprl.cloud:7233 +temporal env set --env prod --key tls-cert-path \ + --value /temporal/certs/prod.pem +temporal env set --env prod --key tls-key-path \ + --value /temporal/certs/prod.key ``` Check your "prod" presets with `temporal env get --env prod`: @@ -347,8 +395,6 @@ Specify an active environment by setting the `TEMPORAL_ENV` environment variable in your shell. The Temporal CLI uses the "default" environment when a specific environment was not named. -Read more: https://docs.temporal.io/cli/env - ### temporal env delete: Delete an environment or environment property Remove an environment entirely or remove a key-value pair within an @@ -378,21 +424,20 @@ and temporal env delete --env prod --key tls-cert-path ``` -If you don't specify an environment, your deletion updates the `default` environment: +If you don't specify an environment, your deletion updates the `default` +environment: ``` temporal env delete --key tls-cert-path ``` -Read more: https://docs.temporal.io/cli/env#delete - #### Options -* `--key`, `-k` (string) - The name of the property +* `--key`, `-k` (string) - Property name ### temporal env get: Print environment properties @@ -432,15 +477,13 @@ tls-key-path /home/my-user/certs/cluster.key When you do not specify an environment name, you list the `default` environment properties. -Read more: https://docs.temporal.io/cli/env#get - #### Options -* `--key`, `-k` (string) - The name of the property +* `--key`, `-k` (string) - Property name ### temporal env list: Print all environments @@ -455,8 +498,6 @@ prod dev ``` -Read more: https://docs.temporal.io/cli/env#list - ### temporal env set: Set environment properties `temporal env set --env environment --key property --value value` @@ -474,8 +515,8 @@ If the environment is not specified, the `default` environment is used. #### Options -* `--key`, `-k` (string) - The name of the property (required) -* `--value`, `-v` (string) - The value to set the property to (required) +* `--key`, `-k` (string) - Property name (required) +* `--value`, `-v` (string) - Property value (required) ### temporal operator: Manage a Temporal deployment @@ -914,7 +955,7 @@ The new build ID will become the default for the set containing the existing ID. * `--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. -### temporal task-queue update-build-ids add-new-default: Add a new default (incompatible) build ID to a Task Queue's version sets +### temporal task-queue update-build-ids add-new-default: Add a new default (incompatible) build ID to a Task Queue's 7 sets 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. From aa491782697dee74fc7889560520eba3c9c59d55 Mon Sep 17 00:00:00 2001 From: Erica Sadun Date: Mon, 20 May 2024 10:45:56 -0600 Subject: [PATCH 18/52] EDU-2415: Pressing onward. Chunk of work, Monday 20 May --- temporalcli/commands.gen.go | 112 +++++---- temporalcli/commandsmd/commands.md | 380 +++++++++++++++++------------ 2 files changed, 296 insertions(+), 196 deletions(-) diff --git a/temporalcli/commands.gen.go b/temporalcli/commands.gen.go index 4c6dc039..6ece25b9 100644 --- a/temporalcli/commands.gen.go +++ b/temporalcli/commands.gen.go @@ -33,9 +33,9 @@ func NewTemporalCommand(cctx *CommandContext) *TemporalCommand { s.Command.Use = "temporal" s.Command.Short = "Temporal command-line interface and development server" if hasHighlighting { - s.Command.Long = "The Temporal CLI (Command Line Interface) provide a powerful tool to manage,\nmonitor, and debug your Temporal applications. It also lets you run a local\nTemporal Service directly from your terminal. With this CLI, you can start\nWorkflows, pass messages, cancel application steps, and more.\n\n* Start a local development service: \n \x1b[1mtemporal server start-dev\x1b[0m \n* Help messages: pass --help for any command:\n \x1b[1mtemporal activity complete --help\x1b[0m" + s.Command.Long = "The Temporal CLI (Command Line Interface) is a powerful tool that manages,\nmonitors, and helps you debug your Temporal applications. With it, you can\nrun a local Temporal Service directly from your terminal. This CLI tool helps\nyou start Workflows, pass messages, cancel application steps, and more.\n\n* Start a local development service:\n \x1b[1mtemporal server start-dev\x1b[0m\n* Help messages: pass --help for any command for how-to details:\n \x1b[1mtemporal activity complete --help\x1b[0m" } else { - s.Command.Long = "The Temporal CLI (Command Line Interface) provide a powerful tool to manage,\nmonitor, and debug your Temporal applications. It also lets you run a local\nTemporal Service directly from your terminal. With this CLI, you can start\nWorkflows, pass messages, cancel application steps, and more.\n\n* Start a local development service: \n `temporal server start-dev` \n* Help messages: pass --help for any command:\n `temporal activity complete --help`" + s.Command.Long = "The Temporal CLI (Command Line Interface) is a powerful tool that manages,\nmonitors, and helps you debug your Temporal applications. With it, you can\nrun a local Temporal Service directly from your terminal. This CLI tool helps\nyou start Workflows, pass messages, cancel application steps, and more.\n\n* Start a local development service:\n `temporal server start-dev`\n* Help messages: pass --help for any command for how-to details:\n `temporal activity complete --help`" } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalActivityCommand(cctx, &s).Command) @@ -48,7 +48,7 @@ func NewTemporalCommand(cctx *CommandContext) *TemporalCommand { s.Command.AddCommand(&NewTemporalWorkflowCommand(cctx, &s).Command) s.Command.PersistentFlags().StringVar(&s.Env, "env", "default", "Active environment name.") cctx.BindFlagEnvVar(s.Command.PersistentFlags().Lookup("env"), "TEMPORAL_ENV") - s.Command.PersistentFlags().StringVar(&s.EnvFile, "env-file", "", "Path to environment settings file (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\".") @@ -74,7 +74,7 @@ func NewTemporalActivityCommand(cctx *CommandContext, parent *TemporalCommand) * s.Parent = parent s.Command.Use = "activity" s.Command.Short = "Complete or fail an Activity" - s.Command.Long = "Update an Activity to report that it has completed or failed. This process\nmarks an activity as successfully finished or as having encountered an error\nduring execution." + s.Command.Long = "Update an Activity to report that it has completed or failed. This command\nmarks an activity as successfully finished or as having encountered an error\nduring execution." s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalActivityCompleteCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalActivityFailCommand(cctx, &s).Command) @@ -98,9 +98,9 @@ func NewTemporalActivityCompleteCommand(cctx *CommandContext, parent *TemporalAc s.Command.Use = "complete [flags]" s.Command.Short = "Complete an Activity" if hasHighlighting { - s.Command.Long = "Complete an Activity, marking it as successfully finished. Specify \nthe ID and include a JSON result to use for the returned value.\n\n\x1b[1mtemporal activity complete \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId \\\n --result '{\"YourResultKey\": \"YourResultVal\"}'\x1b[0m" + s.Command.Long = "Complete an Activity, marking it as successfully finished. Specify\nthe ID and include a JSON result to use 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, marking it as successfully finished. Specify \nthe ID and include a JSON result to use for the returned value.\n\n```\ntemporal activity complete \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId \\\n --result '{\"YourResultKey\": \"YourResultVal\"}'\n```" + s.Command.Long = "Complete an Activity, marking it as successfully finished. Specify\nthe ID and include a JSON result to use 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()) @@ -108,7 +108,7 @@ func NewTemporalActivityCompleteCommand(cctx *CommandContext, parent *TemporalAc _ = cobra.MarkFlagRequired(s.Command.Flags(), "activity-id") s.Command.Flags().StringVar(&s.Result, "result", "", "Result `JSON` for completing the Activity.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "result") - s.Command.Flags().StringVar(&s.Identity, "identity", "", "Identity of the user submitting this request") + 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) @@ -142,9 +142,9 @@ func NewTemporalActivityFailCommand(cctx *CommandContext, parent *TemporalActivi s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "`ID` of the Activity to be failed.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "activity-id") - s.Command.Flags().StringVar(&s.Detail, "detail", "", "JSON data with the reason for failing the Activity") - 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.Flags().StringVar(&s.Detail, "detail", "", "JSON data with the reason for failing the Activity.") + 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 { cctx.Options.Fail(err) @@ -165,9 +165,9 @@ func NewTemporalBatchCommand(cctx *CommandContext, parent *TemporalCommand) *Tem s.Command.Use = "batch" s.Command.Short = "Manage Batch Jobs" if hasHighlighting { - s.Command.Long = "A batch job executes a single command affecting multiple Workflow \nExecutions in tandem. You specify the Workflow Execution\n\nYou select the Workflow Executions to include and the kind of batch \njob to apply. For example, cancel all the running 'YourWorkflow' Workflows:\n\n\x1b[1mtemporal workflow cancel \\\n --query 'ExecutionStatus = \"Running\" AND WorkflowType=\"YourWorkflow\"' \\\n --reason \"Testing\"\x1b[0m" + s.Command.Long = "A batch job executes a single command affecting multiple Workflow\nExecutions in tandem. You specify the Workflow Execution\n\nYou select the Workflow Executions to include and the kind of batch\njob to apply. For example, cancel all the running 'YourWorkflow' Workflows:\n\n\x1b[1mtemporal workflow cancel \\\n --query 'ExecutionStatus = \"Running\" AND WorkflowType=\"YourWorkflow\"' \\\n --reason \"Testing\"\x1b[0m" } else { - s.Command.Long = "A batch job executes a single command affecting multiple Workflow \nExecutions in tandem. You specify the Workflow Execution\n\nYou select the Workflow Executions to include and the kind of batch \njob to apply. For example, cancel all the running 'YourWorkflow' Workflows:\n\n```\ntemporal workflow cancel \\\n --query 'ExecutionStatus = \"Running\" AND WorkflowType=\"YourWorkflow\"' \\\n --reason \"Testing\"\n```" + s.Command.Long = "A batch job executes a single command affecting multiple Workflow\nExecutions in tandem. You specify the Workflow Execution\n\nYou select the Workflow Executions to include and the kind of batch\njob to apply. For example, cancel all the running 'YourWorkflow' Workflows:\n\n```\ntemporal workflow cancel \\\n --query 'ExecutionStatus = \"Running\" AND WorkflowType=\"YourWorkflow\"' \\\n --reason \"Testing\"\n```" } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalBatchDescribeCommand(cctx, &s).Command) @@ -218,9 +218,9 @@ func NewTemporalBatchListCommand(cctx *CommandContext, parent *TemporalBatchComm s.Command.Use = "list [flags]" s.Command.Short = "List all Batch Jobs" if hasHighlighting { - s.Command.Long = "Return a list of Batch jobs, for the entire Service or a single Namespace:\n\n\n\x1b[1mtemporal batch list --namespace YourNamespace\x1b[0m" + s.Command.Long = "Return a list of Batch jobs, for the entire Service or, optionally,\na single Namespace. This example lists the batch jobs for \"YourNamespace\".\n\n\n\x1b[1mtemporal batch list --namespace YourNamespace\x1b[0m" } else { - s.Command.Long = "Return a list of Batch jobs, for the entire Service or a single Namespace:\n\n\n```\ntemporal batch list --namespace YourNamespace\n```" + s.Command.Long = "Return a list of Batch jobs, for the entire Service or, optionally,\na single Namespace. This example lists the batch jobs for \"YourNamespace\".\n\n\n```\ntemporal batch list --namespace YourNamespace\n```" } s.Command.Args = cobra.NoArgs s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Show only the first `N` Batch Jobs in the list.") @@ -246,9 +246,9 @@ func NewTemporalBatchTerminateCommand(cctx *CommandContext, parent *TemporalBatc s.Command.Use = "terminate [flags]" s.Command.Short = "Terminate a Batch Job" if hasHighlighting { - s.Command.Long = "Terminate the Batch job with the provided Job Id. You must provide\na reason motivating the termination, which is stored with the Service\nfor later reference.\n\n\x1b[1mtemporal batch terminate --job-id YourJobId --reason YourTerminationReason\x1b[0m" + s.Command.Long = "Terminate the Batch job with the provided Job Id. You must provide\na reason motivating the termination. This reason is stored with the Service\nfor later reference. For example:\n\n\x1b[1mtemporal batch terminate --job-id YourJobId --reason YourTerminationReason\x1b[0m" } else { - s.Command.Long = "Terminate the Batch job with the provided Job Id. You must provide\na reason motivating the termination, which is stored with the Service\nfor later reference.\n\n```\ntemporal batch terminate --job-id YourJobId --reason YourTerminationReason\n```" + s.Command.Long = "Terminate the Batch job with the provided Job Id. You must provide\na reason motivating the termination. This reason is stored with the Service\nfor later reference. For example:\n\n```\ntemporal batch terminate --job-id YourJobId --reason YourTerminationReason\n```" } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.JobId, "job-id", "", "The Batch Job Id to terminate.") @@ -274,9 +274,9 @@ func NewTemporalEnvCommand(cctx *CommandContext, parent *TemporalCommand) *Tempo s.Command.Use = "env" s.Command.Short = "Manage environments" if hasHighlighting { - s.Command.Long = "Environments help you create and manage grouped key-value presets for Options.\nThey provide easy set-up for separate environments, such as \"dev\" and \n\"prod\" work.\n\nFor example, you might set an endpoint preset for the \x1b[1m--address\x1b[0m option.\nYou won't have to enter it each time you use the Temporal CLI utility. Env \npresets let you configure distinct setups for Temporal Services and Namespaces.\n\nEnvironment names compartmentalize each key-value store. Use the environment\nname as part of your assignment, as in this example, which configures the \n\"prod\" environment:\n\n\x1b[1mtemporal env set --env prod --key namespace \\\n --value production.f45a2 \ntemporal env set --env prod --key address \\\n --value production.f45a2.tmprl.cloud:7233 \ntemporal env set --env prod --key tls-cert-path \\\n --value /temporal/certs/prod.pem \ntemporal env set --env prod --key tls-key-path \\\n --value /temporal/certs/prod.key\x1b[0m\n\nCheck your \"prod\" presets with \x1b[1mtemporal env get --env prod\x1b[0m:\n\n\x1b[1maddress production.f45a2.tmprl.cloud:7233 \nnamespace production.f45a2 \ntls-cert-path /temporal/certs/prod.pem \ntls-key-path /temporal/certs/prod.key\x1b[0m\n\nTo use the environment with a command, pass \x1b[1m--env\x1b[0m followed by the environment\nname. For example, to list workflows in the \"prod\" environment:\n\n\x1b[1m$ temporal workflow list --env prod\x1b[0m\n\nSpecify an active environment by setting the \x1b[1mTEMPORAL_ENV\x1b[0m environment\nvariable in your shell. The Temporal CLI uses the \"default\" environment when a\nspecific environment was not named." + s.Command.Long = "Environments create and manage groups of key-value presets. These presets\nconfigure options for your CLI commands so you don't have to type them in\neach time. Use them for easy set-up for distinct environments, such as \"dev\"\nand \"prod\" work.\n\nFor example, you might set an endpoint preset for the \x1b[1m--address\x1b[0m option\nfor each environment. Supply the \x1b[1m--env\x1b[0m name and the CLI configures the\noptions for you.\n\nEnvironments compartmentalize each of your key-value stores. Changes to\nyour \"prod\" environment do not affect your \"dev\" environment.\n\nConfiguration examples:\n\n\x1b[1mtemporal env set --env prod --key namespace \\\n --value production.f45a2\ntemporal env set --env prod --key address \\\n --value production.f45a2.tmprl.cloud:7233\ntemporal env set --env prod --key tls-cert-path \\\n --value /temporal/certs/prod.pem\ntemporal env set --env prod --key tls-key-path \\\n --value /temporal/certs/prod.key\x1b[0m\n\nCheck your \"prod\" presets using \x1b[1mtemporal env get --env prod\x1b[0m:\n\n\x1b[1maddress production.f45a2.tmprl.cloud:7233\nnamespace production.f45a2\ntls-cert-path /temporal/certs/prod.pem\ntls-key-path /temporal/certs/prod.key\x1b[0m\n\nTo use an environment with any command, pass \x1b[1m--env\x1b[0m followed by the\nenvironment name. For example, to list workflows in the \"prod\" environment:\n\n\x1b[1m$ temporal workflow list --env prod\x1b[0m\n\nFor even easier use, specify your active environment as an environment\nvariable in your shell by setting the \x1b[1mTEMPORAL_ENV\x1b[0m environment variable.\nThe Temporal CLI uses the \"default\" environment when a specific environment\nwas not named in the command or set as an environment variable." } else { - s.Command.Long = "Environments help you create and manage grouped key-value presets for Options.\nThey provide easy set-up for separate environments, such as \"dev\" and \n\"prod\" work.\n\nFor example, you might set an endpoint preset for the `--address` option.\nYou won't have to enter it each time you use the Temporal CLI utility. Env \npresets let you configure distinct setups for Temporal Services and Namespaces.\n\nEnvironment names compartmentalize each key-value store. Use the environment\nname as part of your assignment, as in this example, which configures the \n\"prod\" environment:\n\n```\ntemporal env set --env prod --key namespace \\\n --value production.f45a2 \ntemporal env set --env prod --key address \\\n --value production.f45a2.tmprl.cloud:7233 \ntemporal env set --env prod --key tls-cert-path \\\n --value /temporal/certs/prod.pem \ntemporal env set --env prod --key tls-key-path \\\n --value /temporal/certs/prod.key\n```\n\nCheck your \"prod\" presets with `temporal env get --env prod`:\n\n``` \naddress production.f45a2.tmprl.cloud:7233 \nnamespace production.f45a2 \ntls-cert-path /temporal/certs/prod.pem \ntls-key-path /temporal/certs/prod.key\n```\n\nTo use the environment with a command, pass `--env` followed by the environment\nname. For example, to list workflows in the \"prod\" environment:\n\n```\n$ temporal workflow list --env prod\n```\n\nSpecify an active environment by setting the `TEMPORAL_ENV` environment\nvariable in your shell. The Temporal CLI uses the \"default\" environment when a\nspecific environment was not named." + s.Command.Long = "Environments create and manage groups of key-value presets. These presets\nconfigure options for your CLI commands so you don't have to type them in\neach time. Use them for easy set-up for distinct environments, such as \"dev\"\nand \"prod\" work.\n\nFor example, you might set an endpoint preset for the `--address` option\nfor each environment. Supply the `--env` name and the CLI configures the\noptions for you.\n\nEnvironments compartmentalize each of your key-value stores. Changes to\nyour \"prod\" environment do not affect your \"dev\" environment.\n\nConfiguration examples:\n\n```\ntemporal env set --env prod --key namespace \\\n --value production.f45a2\ntemporal env set --env prod --key address \\\n --value production.f45a2.tmprl.cloud:7233\ntemporal env set --env prod --key tls-cert-path \\\n --value /temporal/certs/prod.pem\ntemporal env set --env prod --key tls-key-path \\\n --value /temporal/certs/prod.key\n```\n\nCheck your \"prod\" presets using `temporal env get --env prod`:\n\n```\naddress production.f45a2.tmprl.cloud:7233\nnamespace production.f45a2\ntls-cert-path /temporal/certs/prod.pem\ntls-key-path /temporal/certs/prod.key\n```\n\nTo use an environment with any command, pass `--env` followed by the\nenvironment name. For example, to list workflows in the \"prod\" environment:\n\n```\n$ temporal workflow list --env prod\n```\n\nFor even easier use, specify your active environment as an environment\nvariable in your shell by setting the `TEMPORAL_ENV` environment variable.\nThe Temporal CLI uses the \"default\" environment when a specific environment\nwas not named in the command or set as an environment variable." } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalEnvDeleteCommand(cctx, &s).Command) @@ -299,12 +299,12 @@ func NewTemporalEnvDeleteCommand(cctx *CommandContext, parent *TemporalEnvComman s.Command.Use = "delete [flags]" s.Command.Short = "Delete an environment or environment property" if hasHighlighting { - s.Command.Long = "Remove an environment entirely or remove a key-value pair within an\nenvironment.\n\nRemove an environment:\n\n\x1b[1mtemporal env delete --env YourEnvironment\x1b[0m\n\nRemove a key-value pair from an environment:\n\n\x1b[1mtemporal env delete --env YourEnvironment --key YourKey\x1b[0m\n\nFor example:\n\n\x1b[1mtemporal env delete --env prod\x1b[0m\n\nand\n\n\x1b[1mtemporal env delete --env prod --key tls-cert-path\x1b[0m\n\nIf you don't specify an environment, your deletion updates the \x1b[1mdefault\x1b[0m environment:\n\n\x1b[1mtemporal env delete --key tls-cert-path\x1b[0m" + s.Command.Long = "Remove an environment entirely or remove a key-value pair within an\nenvironment. When you don't specify an environment (with \x1b[1m--env\x1b[0m or by\nsetting the \x1b[1mTEMPORAL_ENV\x1b[0m environment variable), you update the \x1b[1mdefault\x1b[0m\nenvironment.\n\n\x1b[1mtemporal env delete --env YourEnvironment\x1b[0m\n\nor\n\n\x1b[1mtemporal env delete --env prod --key tls-key-path\x1b[0m" } else { - s.Command.Long = "Remove an environment entirely or remove a key-value pair within an\nenvironment.\n\nRemove an environment:\n\n```\ntemporal env delete --env YourEnvironment\n```\n\nRemove a key-value pair from an environment:\n\n```\ntemporal env delete --env YourEnvironment --key YourKey\n```\n\nFor example:\n\n```\ntemporal env delete --env prod\n```\n\nand\n\n```\ntemporal env delete --env prod --key tls-cert-path\n```\n\nIf you don't specify an environment, your deletion updates the `default` environment:\n\n```\ntemporal env delete --key tls-cert-path\n```" + s.Command.Long = "Remove an environment entirely or remove a key-value pair within an\nenvironment. When you don't specify an environment (with `--env` or by\nsetting the `TEMPORAL_ENV` environment variable), you update the `default`\nenvironment.\n\n```\ntemporal env delete --env YourEnvironment\n```\n\nor\n\n```\ntemporal env delete --env prod --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) @@ -326,12 +326,12 @@ func NewTemporalEnvGetCommand(cctx *CommandContext, parent *TemporalEnvCommand) s.Command.Use = "get [flags]" s.Command.Short = "Print environment properties" if hasHighlighting { - s.Command.Long = "Prints the environmental properties for a given environment:\n\n\x1b[1mtemporal env get --env environment-name\x1b[0m\n\nPrint all properties of the \"prod\" environment:\n\n\x1b[1mtemporal env get --env prod\x1b[0m\n\nmight produce these results:\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 --key tls-key-path\x1b[0m\n\nmight produce this result:\n\n\x1b[1mtls-key-path /home/my-user/certs/cluster.key\x1b[0m\n\nWhen you do not specify an environment name, you list the \x1b[1mdefault\x1b[0m\nenvironment properties." + s.Command.Long = "Print the environmental properties for a given environment:\n\n\x1b[1mtemporal env get --env YourEnvironment\x1b[0m\n\nFor example, invoking:\n\n\x1b[1mtemporal env get --env prod\x1b[0m\n\nmight produce these results:\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 --key tls-key-path\x1b[0m\n\nmight produce this result:\n\n\x1b[1mtls-key-path /home/my-user/certs/cluster.key\x1b[0m\n\nIf you do not specify an environment name, either directly with the \x1b[1m--env\x1b[0m\noption or indirectly by setting the \x1b[1mTEMPORAL_ENV\x1b[0m environmental variable,\nyou list the \x1b[1mdefault\x1b[0m environment properties." } else { - s.Command.Long = "Prints the environmental properties for a given environment:\n\n```\ntemporal env get --env environment-name\n```\n\nPrint all properties of the \"prod\" environment:\n\n```\ntemporal env get --env prod\n```\n\nmight produce these results:\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```\ntemporal env get --env prod --key tls-key-path\n```\n\nmight produce this result:\n\n```\ntls-key-path /home/my-user/certs/cluster.key\n```\n\nWhen you do not specify an environment name, you list the `default`\nenvironment properties." + s.Command.Long = "Print the environmental properties for a given environment:\n\n```\ntemporal env get --env YourEnvironment\n```\n\nFor example, invoking:\n\n```\ntemporal env get --env prod\n```\n\nmight produce these results:\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```\ntemporal env get --env prod --key tls-key-path\n```\n\nmight produce this result:\n\n```\ntls-key-path /home/my-user/certs/cluster.key\n```\n\nIf you do not specify an environment name, either directly with the `--env`\noption or indirectly by setting the `TEMPORAL_ENV` environmental variable,\nyou list the `default` environment properties." } 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) @@ -352,9 +352,9 @@ func NewTemporalEnvListCommand(cctx *CommandContext, parent *TemporalEnvCommand) s.Command.Use = "list [flags]" s.Command.Short = "Print all environments" if hasHighlighting { - s.Command.Long = "STOPPED HERE FOR SANITY CHECK AND REVIEW BY JOSH BEFORE CONTINUING OR REDIRECTING\n\nList the environments you have set up on your local computer with\n\x1b[1mtemporal env list\x1b[0m. For example:\n\n\x1b[1mdefault \nprod\ndev\x1b[0m" + s.Command.Long = "List the environments you have previously set up on your local computer\nby issuing \x1b[1mtemporal env list\x1b[0m. Your output shows all environment names\ncurrently stored in your \"$HOME/.config/temporalio/temporal.yaml\" file.\n\n\x1b[1mdefault\nprod\ndev\x1b[0m" } else { - s.Command.Long = "STOPPED HERE FOR SANITY CHECK AND REVIEW BY JOSH BEFORE CONTINUING OR REDIRECTING\n\nList the environments you have set up on your local computer with\n`temporal env list`. For example:\n\n```\ndefault \nprod\ndev\n```" + s.Command.Long = "List the environments you have previously set up on your local computer\nby issuing `temporal env list`. Your output shows all environment names\ncurrently stored in your \"$HOME/.config/temporalio/temporal.yaml\" file.\n\n```\ndefault\nprod\ndev\n```" } s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { @@ -379,13 +379,13 @@ func NewTemporalEnvSetCommand(cctx *CommandContext, parent *TemporalEnvCommand) s.Command.Use = "set [flags]" s.Command.Short = "Set environment properties" if hasHighlighting { - s.Command.Long = "\x1b[1mtemporal env set --env environment --key property --value 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 --key address --value 127.0.0.1:7233\x1b[0m\n\x1b[1mtemporal env set --env prod --key tls-cert-path --value /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 = "Associate a value with a property key and store it in the environment you\nspecify with the \x1b[1m--env\x1b[0m flag or have set with the \x1b[1mTEMPORAL_ENV\x1b[0m\nenvironmental variable.\n\n\x1b[1mtemporal env set --env environment --key property --value value\x1b[0m\n\nProperty names match should match CLI option names. This enables\nthem to be automatically retrieved for the active environment. Setting\nproperty values in advance reduces the effort required to issue CLI commands\nand helps avoid typos.\n\nFor example, '--address' and '--tls-cert-path':\n\n\x1b[1mtemporal env set --env prod --key address --value 127.0.0.1:7233\ntemporal env set \\\n --env prod --key tls-cert-path \\\n --value /home/my-user/certs/cluster.cert\x1b[0m\n\nWhen an environment is not specified, the CLI tool uses the \x1b[1mdefault\x1b[0m\nenvironment." } else { - s.Command.Long = "`temporal env set --env environment --key property --value value`\n\nProperty names match CLI option names, for example '--address' and '--tls-cert-path':\n\n`temporal env set --env prod --key address --value 127.0.0.1:7233`\n`temporal env set --env prod --key tls-cert-path --value /home/my-user/certs/cluster.cert`\n\nIf the environment is not specified, the `default` environment is used." + s.Command.Long = "Associate a value with a property key and store it in the environment you\nspecify with the `--env` flag or have set with the `TEMPORAL_ENV`\nenvironmental variable.\n\n```\ntemporal env set --env environment --key property --value value\n```\n\nProperty names match should match CLI option names. This enables\nthem to be automatically retrieved for the active environment. Setting\nproperty values in advance reduces the effort required to issue CLI commands\nand helps avoid typos.\n\nFor example, '--address' and '--tls-cert-path':\n\n```\ntemporal env set --env prod --key address --value 127.0.0.1:7233\ntemporal env set \\\n --env prod --key tls-cert-path \\\n --value /home/my-user/certs/cluster.cert\n```\n\nWhen an environment is not specified, the CLI tool uses the `default`\nenvironment." } s.Command.Args = cobra.MaximumNArgs(2) - s.Command.Flags().StringVarP(&s.Key, "key", "k", "", "The name of the property (required)") - s.Command.Flags().StringVarP(&s.Value, "value", "v", "", "The value to set the property to (required)") + 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) @@ -405,7 +405,11 @@ func NewTemporalOperatorCommand(cctx *CommandContext, parent *TemporalCommand) * s.Parent = parent s.Command.Use = "operator" s.Command.Short = "Manage a Temporal deployment" - s.Command.Long = "Operator commands perform actions on Namespaces, Search Attributes, and Temporal Clusters." + if hasHighlighting { + s.Command.Long = "Operator commands perform actions on and retrieve information about\nNamespaces, Search Attributes, and Temporal Clusters.\n\nTo run an Operator command, issue:\n\n\x1b[1mtemporal operator [command] [subcommand] [options]\x1b[0m" + } else { + s.Command.Long = "Operator commands perform actions on and retrieve information about\nNamespaces, Search Attributes, and Temporal Clusters.\n\nTo run an Operator command, issue:\n\n```\ntemporal operator [command] [subcommand] [options]\n```" + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalOperatorClusterCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalOperatorNamespaceCommand(cctx, &s).Command) @@ -424,7 +428,11 @@ func NewTemporalOperatorClusterCommand(cctx *CommandContext, parent *TemporalOpe s.Parent = parent s.Command.Use = "cluster" s.Command.Short = "Operations for running a Temporal Cluster" - s.Command.Long = "Cluster commands perform actions on Temporal Clusters." + if hasHighlighting { + s.Command.Long = "Perform actions on Temporal Clusters.\n\n\x1b[1mtemporal operator cluster [subcommand] [options]\x1b[0m" + } else { + s.Command.Long = "Perform actions on Temporal Clusters.\n\n```\ntemporal operator cluster [subcommand] [options]\n```" + } s.Command.Args = cobra.NoArgs s.Command.AddCommand(&NewTemporalOperatorClusterDescribeCommand(cctx, &s).Command) s.Command.AddCommand(&NewTemporalOperatorClusterHealthCommand(cctx, &s).Command) @@ -447,9 +455,13 @@ func NewTemporalOperatorClusterDescribeCommand(cctx *CommandContext, parent *Tem s.Command.DisableFlagsInUseLine = true s.Command.Use = "describe [flags]" s.Command.Short = "Describe a cluster" - s.Command.Long = "" + if hasHighlighting { + s.Command.Long = "View information about a cluster.\n\n\x1b[1mtemporal operator cluster describe [options]\x1b[0m" + } else { + s.Command.Long = "View information about a cluster.\n\n```\ntemporal operator cluster describe [options]\n```" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().BoolVar(&s.Detail, "detail", false, "Show extra details") + s.Command.Flags().BoolVar(&s.Detail, "detail", false, "Include high-detail output.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -469,7 +481,11 @@ func NewTemporalOperatorClusterHealthCommand(cctx *CommandContext, parent *Tempo s.Command.DisableFlagsInUseLine = true s.Command.Use = "health [flags]" s.Command.Short = "Check the health of a cluster" - s.Command.Long = "" + if hasHighlighting { + s.Command.Long = "View information about the health of the Frontend Service.\n\n\x1b[1mtemporal operator cluster health\x1b[0m" + } else { + s.Command.Long = "View information about the health of the Frontend Service.\n\n```\ntemporal operator cluster health\n```" + } s.Command.Args = cobra.NoArgs s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -491,9 +507,13 @@ func NewTemporalOperatorClusterListCommand(cctx *CommandContext, parent *Tempora s.Command.DisableFlagsInUseLine = true s.Command.Use = "list [flags]" s.Command.Short = "List all remote clusters" - s.Command.Long = "" + if hasHighlighting { + s.Command.Long = "Print a list of the remote Clusters on this system.\n\n\x1b[1mtemporal operator cluster list [--limit N]\x1b[0m" + } else { + s.Command.Long = "Print a list of the remote Clusters on this system.\n\n```\ntemporal operator cluster list [--limit N]\n```" + } s.Command.Args = cobra.NoArgs - s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Show only the first `N` clusters in the list.") + s.Command.Flags().IntVar(&s.Limit, "limit", 0, "Show the first `N` clusters from the list.") s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { cctx.Options.Fail(err) @@ -514,7 +534,11 @@ func NewTemporalOperatorClusterRemoveCommand(cctx *CommandContext, parent *Tempo s.Command.DisableFlagsInUseLine = true s.Command.Use = "remove [flags]" s.Command.Short = "Remove a remote cluster" - s.Command.Long = "" + if hasHighlighting { + s.Command.Long = "Remove a remote cluster from this system.\n\n\x1b[1mtemporal operator cluster remove --name YourClusterName\x1b[0m" + } else { + s.Command.Long = "Remove a remote cluster from this system.\n\n```\ntemporal operator cluster remove --name YourClusterName\n```" + } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.Name, "name", "", "Name of cluster.") _ = cobra.MarkFlagRequired(s.Command.Flags(), "name") @@ -536,7 +560,7 @@ 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 = "Provide system info TAKING A BREAK HERE WEFWEF" 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." } else { @@ -633,11 +657,11 @@ func NewTemporalOperatorNamespaceCreateCommand(cctx *CommandContext, parent *Tem 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 YourCluster -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.Args = cobra.MaximumNArgs(1) - s.Command.Flags().StringVar(&s.ActiveCluster, "active-cluster", "", "Active cluster name") + s.Command.Flags().StringVar(&s.ActiveCluster, "active-cluster", "", "Active cluster name.") s.Command.Flags().StringArrayVar(&s.Cluster, "cluster", nil, "Cluster names. \"--cluster\" may be passed multiple times to specify multiple clusters.") s.Command.Flags().StringVar(&s.Data, "data", "", "Namespace data in `KEY=VALUE` format, separated by commas. `KEY` and `VALUE` may be arbitrary strings.") - s.Command.Flags().StringVar(&s.Description, "description", "", "Namespace description") - s.Command.Flags().StringVar(&s.Email, "email", "", "Owner email") + 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, "Enable cross-region replication for this namespace.") s.HistoryArchivalState = NewStringEnum([]string{"disabled", "enabled"}, "disabled") s.Command.Flags().Var(&s.HistoryArchivalState, "history-archival-state", "History archival state. Accepted values: disabled, enabled.") @@ -753,8 +777,8 @@ func NewTemporalOperatorNamespaceUpdateCommand(cctx *CommandContext, parent *Tem 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.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().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, "Set a `KEY=VALUE` pair in namespace data. `KEY` and `VALUE` may be arbitrary strings, but JSON is recommended for `VALUE`. May be used multiple times to set multiple pairs.") s.Command.Flags().StringVar(&s.Description, "description", "", "Namespace description") s.Command.Flags().StringVar(&s.Email, "email", "", "Owner email") diff --git a/temporalcli/commandsmd/commands.md b/temporalcli/commandsmd/commands.md index d4fe09fa..0210f9e7 100644 --- a/temporalcli/commandsmd/commands.md +++ b/temporalcli/commandsmd/commands.md @@ -6,7 +6,7 @@ Commands for the Temporal CLI. NOTES FOR ERICA -* Word wrapping to 80 chars. +* Word wrapping to 80 chars. * What about options? they tend to run long * Could the text go to a second line after the spaced-dash? * Key-value space vs equal (I want space) @@ -31,7 +31,7 @@ Flags: -v, --version version for temporal Non-discussion -Josh: "The available subcommands are already listed by the help output, +Josh: "The available subcommands are already listed by the help output, so you don't have to include them here" ----- @@ -41,14 +41,19 @@ Follow these rules. IN-HOUSE STYLE -* Use alphabetical order for commands. -* Commands with subcommands cannot be run on their own. * User-visible line length: 80 characters max. -* Add punctuation consistently, even at the end of phrases. +* Use alphabetical order for commands. * Short descriptions do not end with a period. -* Every long description demonstrates at least one example use of the command. +* Use punctuation consistently in long descriptions, + even at the end of phrases. +* Every long description demonstrates at least one + example use of the command. + * Use YourEnvironment, YourNamespace, etc as metasyntactic stand-ins. +* Commands with subcommands cannot be run on their own. + * Use full command examples that do not imply otherwise. * When presenting options use a space rather than equal to set them. - This is more universally supported and consistent with POSIX guidelines. + This is more universally supported and consistent with + POSIX guidelines. * Yes: `temporal command --namespace YourNamespace` * No: `temporal command --namespace=YourNamespace` * Use imperative-form verbs: @@ -57,29 +62,30 @@ IN-HOUSE STYLE For options and flags: -* When flags can be passed multiple times, say so explicitly in the usage text. -* Do not rely on the flag type (e.g. `string`, `bool`, etc.) - being shown to the user. +* When flags can be passed multiple times, say so explicitly in + the usage text. +* Do not rely on the flag type (e.g. `string`, `bool`, etc.) being + shown to the user. It is hidden if a `META-VARIABLE` is used. -* Where possible, use a `META-VARIABLE` (all caps and wrapped in `\``s) +* Where possible, use a `META-VARIABLE` (all caps and wrapped in `\``s) to describe/reference content passed to an option. -* Limit `code spans` to meta-variables. +* Limit `code spans` to meta-variables. To reference other options or specify literal values, use double quotes. * Avoid parentheticals unless absolutely necessary. -Examples: +Examples: These show correct/incorrect usage text for the optional `--history-uri` flag: * Preferred: "Archive history at \`URI\`. " -* Avoid incomplete sentences: +* Avoid incomplete sentences: "_History archival \`URI\`_. " -* Avoid wrong verb tenses: +* Avoid wrong verb tenses: "_Archives history at \`URI\`_. " * Avoid missing metavariables: "Archive history at _the specified URI_. " -* Avoid unnecessary parenthetical: +* Avoid unnecessary parenthetical: `Archive history at \`URI\` _(note: )_.` @@ -88,7 +94,7 @@ COMMAND ENTRY OVERVIEW A Command entry uses the following format: ### : - + (optional command implementation configuration) @@ -108,19 +114,19 @@ COMMAND LISTING * One line only. Use the complete command path with parent commands. * Use square-bracked delimited arguments to document positional arguments. For example `temporal operator namespace delete [namespace]`. - * Everything up to ':' or '[' is the command. + * Everything up to ':' or '[' is the command. Square-bracketed positional arguments are not part of the command. - * Everything following the ':' or '[' is used for the short-description, + * Everything following the ':' or '[' is used for the short-description, a concise command explanation. -* A command's long description continues until encountering the H4 +* A command's long description continues until encountering the H4 (`#### Options`) header. -* At the end of the long description, an optional XML comment configures +* At the end of the long description, an optional XML comment configures the command implementation. Use one asterisk-delimited bullet per line. * `* has-init` - invokes `initCommand` method. * `* exact-args=` - Require this exact number of args. * `* maximum-args=` - Require this maximum number of args. - + LONG DESCRIPTION SECTION * Your text format is preserved literally, so be careful with line lengths. @@ -130,29 +136,29 @@ OPTIONS SECTION * Start the optional Options section with an H4 `#### Options` header line. * Follow the header declaration with a list of options. -* In the current implementation, you must include at least one option. - Otherwise, although `gen-commands` will complete, the CLI utility will +* In the current implementation, you must include at least one option. + Otherwise, although `gen-commands` will complete, the CLI utility will not run. -* To incorporate an existing options set, add a single line below options - like this, remembering to end every `Include options set for` line with a +* To incorporate an existing options set, add a single line below options + like this, remembering to end every `Include options set for` line with a period. ``` Includes options set for [](#options-set-for-). ``` - + For example: - + ``` Includes options set for [client](#options-set-for-client). ``` - - An options set declaration is the equivalent of pasting those options into + + An options set declaration is the equivalent of pasting those options into the bulleted options list. - Note: Options that are similar but slightly different don't need to be in + Note: Options that are similar but slightly different don't need to be in option sets. - Reserve option sets for when the behavior of the option is the same across + Reserve option sets for when the behavior of the option is the same across commands. Copy/paste is fine, otherwise. @@ -165,37 +171,39 @@ DEFINING AN OPTION ``` `--`( , `-`) - ( ) ``` - - This contrived example uses all these features. - In reality, the short option `-a` does not actually exist alongside + + This contrived example uses all these features. + In reality, the short option `-a` does not actually exist alongside `--address`: - + ``` - * `--address`, `-a` (string) - Connect to the Temporal Service at `HOST:PORT`. Default: 127.0.0.1:7233. Env: TEMPORAL_ADDRESS. + * `--address`, `-a` (string) - + Connect to the Temporal Service at `HOST:PORT`. + Default: 127.0.0.1:7233. Env: TEMPORAL_ADDRESS. ``` -* Each option listing includes a long option with a double dash and a +* Each option listing includes a long option with a double dash and a meaningful name. * [Optional] A short option uses a single dash and a short string. When used, separate the long and short option with a comma and a space. -* Backtick every option and short description. +* Backtick every option and short description. Include the dash or dashes within the ticks. For example: `` `--workflow-id`, `-w` `` * A data type follows option names indicating the required value type for the option. - The type is `bool`, `duration`, `int`, `string`, `string[]`, `string-enum`, + The type is `bool`, `duration`, `int`, `string`, `string[]`, `string-enum`, or `timestamp`. (_TODO: more_.) Always parenthesize data types. For example: `` `--raw` (bool) `` -* A dash follows the data type, with a space on either side. +* A dash follows the data type, with a space on either side. * The short description is free-form text and follows the dash. - Take care not to match trailing attributes. + Take care not to match trailing attributes. Newline wrapping and/or two-space indentation condenses to a single space. * [Optional] extra attributes include: * `Required.` - Marks the option as required. - * `Default: .` - Sets the default value of the option. + * `Default: .` - Sets the default value of the option. No default means zero value of the type. - * `Options: