README
¶
What
Cadence CLI is a command-line tool to perform various tasks on a Cadence server. It can perform domain operations such as register, update, and describe as well as workflow operations like start workflow, show workflow history, and signal workflow.
How
- Run
make bins
- You should see an executable
cadence
- (Optional) You could also use docker image
ubercadence/cli
, by replacing all the following./cadence ...
withdocker run --rm ubercadence/cli:master ...
Quick Start
Run ./cadence
for help on top level commands and global options
Run ./cadence domain
for help on domain operations
Run ./cadence workflow
for help on workflow operations
Run ./cadence tasklist
for help on tasklist operations
(./cadence help
, ./cadence help [domain|workflow]
will also print help messages)
Note: make sure you have cadence server running before using CLI
Domain operation examples
- Register a new domain named "samples-domain":
./cadence --domain samples-domain domain register
# OR using short alias
./cadence --do samples-domain domain re
- View "samples-domain" details:
./cadence --domain samples-domain domain describe
Tip:
To avoid repeatedly including the global option --domain,
export domain-name to the CADENCE_CLI_DOMAIN environment variable.
export CADENCE_CLI_DOMAIN=samples-domain
Then commands can omit the --domain flag:
./cadence domain desc
Workflow operation examples
(The following examples assume the CADENCE_CLI_DOMAIN environment variable is set using the tip above)
Run workflow: Start a workflow and see it's progress. This command doesn't finish until workflow completes.
./cadence workflow run --tl helloWorldGroup --wt main.Workflow --et 60 -i '"cadence"'
# view help messages for workflow run
./cadence workflow run -h
Brief explanation:
To run a workflow, user must specify
- Tasklist name (--tl),
- Workflow type (--wt),
- Execution start to close timeout in seconds (--et),
Example uses this cadence-samples workflow
and takes a string as input with the -i '"cadence"'
parameter. Single quotes (''
) are used to wrap input as json.
Note: you need to start the worker so that workflow can make progress.
(Run make && ./bin/helloworld -m worker
in cadence-samples to start the worker)
Show running workers of a tasklist
./cadence tasklist desc --tl helloWorldGroup
Start workflow
./cadence workflow start --tl helloWorldGroup --wt main.Workflow --et 60 -i '"cadence"'
# view help messages for workflow start
./cadence workflow start -h
# for workflow with multiple input, separate each json with space/newline like
./cadence workflow start --tl helloWorldGroup --wt main.WorkflowWith3Args --et 60 -i '"your_input_string" 123 {"Name":"my-string", "Age":12345}'
The workflow start
command is similar to the run
command, but immediately returns the workflow_id and
run_id after starting the workflow. Use the show
command to view the workflow's history/progress.
Re-use the same workflow id when starting/running workflow
Use option --workflowidreusepolicy
or --wrp
to configure the workflow id re-use policy.
Option 0 AllowDuplicateFailedOnly: Allow starting a workflow execution using the same workflow ID when a workflow with the same workflow ID is not already running and the last execution close state is one of [terminated, cancelled, timedout, failed].
Option 1 AllowDuplicate: Allow starting a workflow execution using the same workflow ID when a workflow with the same workflow ID is not already running.
Option 2 RejectDuplicate: Do not allow starting a workflow execution using the same workflow ID as a previous workflow.
# use AllowDuplicateFailedOnly option to start a workflow
./cadence workflow start --tl helloWorldGroup --wt main.Workflow --et 60 -i '"cadence"' --wid "<duplicated workflow id>" --wrp 0
# use AllowDuplicate option to run a workflow
./cadence workflow run --tl helloWorldGroup --wt main.Workflow --et 60 -i '"cadence"' --wid "<duplicated workflow id>" --wrp 1
Show workflow history
./cadence workflow show -w 3ea6b242-b23c-4279-bb13-f215661b4717 -r 866ae14c-88cf-4f1e-980f-571e031d71b0
# a shortcut of this is (without -w -r flag)
./cadence workflow showid 3ea6b242-b23c-4279-bb13-f215661b4717 866ae14c-88cf-4f1e-980f-571e031d71b0
# if run_id is not provided, it will show the latest run history of that workflow_id
./cadence workflow show -w 3ea6b242-b23c-4279-bb13-f215661b4717
# a shortcut of this is
./cadence workflow showid 3ea6b242-b23c-4279-bb13-f215661b4717
Show workflow execution info
./cadence workflow describe -w 3ea6b242-b23c-4279-bb13-f215661b4717 -r 866ae14c-88cf-4f1e-980f-571e031d71b0
# a shortcut of this is (without -w -r flag)
./cadence workflow describeid 3ea6b242-b23c-4279-bb13-f215661b4717 866ae14c-88cf-4f1e-980f-571e031d71b0
# if run_id is not provided, it will show the latest workflow execution of that workflow_id
./cadence workflow describe -w 3ea6b242-b23c-4279-bb13-f215661b4717
# a shortcut of this is
./cadence workflow describeid 3ea6b242-b23c-4279-bb13-f215661b4717
List closed or open workflow executions
./cadence workflow list
# default will only show one page, to view more items, use --more flag
./cadence workflow list -m
Query workflow execution
# use custom query type
./cadence workflow query -w <wid> -r <rid> --qt <query-type>
# use build-in query type "__stack_trace" which is supported by cadence client library
./cadence workflow query -w <wid> -r <rid> --qt __stack_trace
# a shortcut to query using __stack_trace is (without --qt flag)
./cadence workflow stack -w <wid> -r <rid>
Signal, cancel, terminate workflow
# signal
./cadence workflow signal -w <wid> -r <rid> -n <signal-name> -i '"signal-value"'
# cancel
./cadence workflow cancel -w <wid> -r <rid>
# terminate
./cadence workflow terminate -w <wid> -r <rid> --reason
Terminating a running workflow execution will record a WorkflowExecutionTerminated event as the closing event in the history. No more decision tasks will be scheduled for a terminated workflow execution.
Canceling a running workflow execution will record a WorkflowExecutionCancelRequested event in the history, and a new decision task will be scheduled. The workflow has a chance to do some clean up work after cancellation.
Restart, reset workflow
The Reset command allows resetting a workflow to a particular point and continue running from there. There are a lot of use cases:
- Rerun a failed workflow from the beginning with the same start parameters.
- Rerun a failed workflow from the failing point without losing the achieved progress(history).
- After deploying new code, reset an open workflow to let the workflow run to different flows.
You can reset to some predefined event types:
./cadence workflow reset -w <wid> -r <rid> --reset_type <reset_type> --reason "some_reason"
- FirstDecisionCompleted: reset to the beginning of the history.
- LastDecisionCompleted: reset to the end of the history.
- LastContinuedAsNew: reset to the end of the history for the previous run.
If you are familiar with the Cadence history event, You can also reset to any decision finish event by using:
./cadence workflow reset -w <wid> -r <rid> --event_id <decision_finish_event_id> --reason "some_reason"
Some things to note:
- When reset, a new run will be kicked off with the same workflowID. But if there is a running execution for the workflow(workflowID), the current run will be terminated.
- decision_finish_event_id is the ID of events of the type: DecisionTaskComplete/DecisionTaskFailed/DecisionTaskTimeout.
- To restart a workflow from the beginning, reset to the first decision task finish event.
To reset multiple workflows, you can use batch reset command:
./cadence workflow reset-batch --input_file <file_of_workflows_to_reset> --reset_type <reset_type> --reason "some_reason"
Documentation
¶
Index ¶
- Constants
- func AdminCatIndices(c *cli.Context)
- func AdminDeleteWorkflow(c *cli.Context)
- func AdminDescribeHistoryHost(c *cli.Context)
- func AdminDescribeTaskList(c *cli.Context)
- func AdminDescribeWorkflow(c *cli.Context)
- func AdminGetDomainIDOrName(c *cli.Context)
- func AdminGetShardID(c *cli.Context)
- func AdminIndex(c *cli.Context)
- func AdminKafkaParse(c *cli.Context)
- func AdminMergeDLQ(c *cli.Context)
- func AdminPurgeTopic(c *cli.Context)
- func AdminRereplicate(c *cli.Context)
- func AdminShowWorkflow(c *cli.Context)
- func CancelWorkflow(c *cli.Context)
- func ColorEvent(e *s.HistoryEvent) string
- func CompleteActivity(c *cli.Context)
- func DescribeDomain(c *cli.Context)
- func DescribeTaskList(c *cli.Context)
- func DescribeWorkflow(c *cli.Context)
- func DescribeWorkflowWithID(c *cli.Context)
- func ErrorAndExit(msg string, err error)
- func FailActivity(c *cli.Context)
- func GetHistory(ctx context.Context, workflowClient client.Client, workflowID, runID string) (*s.History, error)
- func HistoryEventToString(e *s.HistoryEvent, printFully bool, maxFieldLength int) string
- func ListAllWorkflow(c *cli.Context)
- func ListWorkflow(c *cli.Context)
- func NewCliApp() *cli.App
- func ObserveHistory(c *cli.Context)
- func ObserveHistoryWithID(c *cli.Context)
- func QueryWorkflow(c *cli.Context)
- func QueryWorkflowUsingStackTrace(c *cli.Context)
- func RegisterDomain(c *cli.Context)
- func ResetInBatch(c *cli.Context)
- func ResetWorkflow(c *cli.Context)
- func RunWorkflow(c *cli.Context)
- func SetFactory(factory ClientFactory)
- func SetRequiredDomainDataKeys(keys []string)
- func ShowHistory(c *cli.Context)
- func ShowHistoryWithWID(c *cli.Context)
- func SignalWorkflow(c *cli.Context)
- func StartWorkflow(c *cli.Context)
- func TerminateWorkflow(c *cli.Context)
- func UpdateDomain(c *cli.Context)
- type ClientFactory
- type ClustersConfig
- type JSONHistorySerializer
Constants ¶
const ( FlagPort = "port" FlagUsername = "username" FlagPassword = "password" FlagKeyspace = "keyspace" FlagAddress = "address" FlagAddressWithAlias = FlagAddress + ", ad" FlagHistoryAddress = "history_address" FlagHistoryAddressWithAlias = FlagHistoryAddress + ", had" FlagDomainID = "domain_id" FlagDomain = "domain" FlagDomainWithAlias = FlagDomain + ", do" FlagShardID = "shard_id" FlagShardIDWithAlias = FlagShardID + ", sid" FlagWorkflowID = "workflow_id" FlagWorkflowIDWithAlias = FlagWorkflowID + ", wid, w" FlagRunID = "run_id" FlagTreeID = "tree_id" FlagBranchID = "branch_id" FlagNumberOfShards = "number_of_shards" FlagRunIDWithAlias = FlagRunID + ", rid, r" FlagTargetCluster = "target_cluster" FlagMinEventID = "min_event_id" FlagMaxEventID = "max_event_id" FlagTaskList = "tasklist" FlagTaskListWithAlias = FlagTaskList + ", tl" FlagTaskListType = "tasklisttype" FlagTaskListTypeWithAlias = FlagTaskListType + ", tlt" FlagWorkflowIDReusePolicy = "workflowidreusepolicy" FlagWorkflowIDReusePolicyAlias = FlagWorkflowIDReusePolicy + ", wrp" FlagCronSchedule = "cron" FlagWorkflowType = "workflow_type" FlagWorkflowTypeWithAlias = FlagWorkflowType + ", wt" FlagWorkflowStatus = "status" FlagWorkflowStatusWithAlias = FlagWorkflowStatus + ", s" FlagExecutionTimeout = "execution_timeout" FlagExecutionTimeoutWithAlias = FlagExecutionTimeout + ", et" FlagDecisionTimeout = "decision_timeout" FlagDecisionTimeoutWithAlias = FlagDecisionTimeout + ", dt" FlagContextTimeout = "context_timeout" FlagContextTimeoutWithAlias = FlagContextTimeout + ", ct" FlagInput = "input" FlagInputWithAlias = FlagInput + ", i" FlagInputFile = "input_file" FlagInputFileWithAlias = FlagInputFile + ", if" FlagExcludeFile = "exclude_file" FlagInputSeparator = "input_separator" FlagParallism = "input_parallism" FlagSkipCurrent = "skip_current_open" FlagInputTopic = "input_topic" FlagInputTopicWithAlias = FlagInputTopic + ", it" FlagHostFile = "host_file" FlagCluster = "cluster" FlagInputCluster = "input_cluster" FlagStartOffset = "start_offset" FlagTopic = "topic" FlagGroup = "group" FlagResult = "result" FlagIdentity = "identity" FlagDetail = "detail" FlagReason = "reason" FlagReasonWithAlias = FlagReason + ", re" FlagOpen = "open" FlagOpenWithAlias = FlagOpen + ", op" FlagMore = "more" FlagMoreWithAlias = FlagMore + ", m" FlagPageSize = "pagesize" FlagPageSizeWithAlias = FlagPageSize + ", ps" FlagEarliestTime = "earliest_time" FlagEarliestTimeWithAlias = FlagEarliestTime + ", et" FlagLatestTime = "latest_time" FlagLatestTimeWithAlias = FlagLatestTime + ", lt" FlagPrintEventVersion = "print_event_version" FlagPrintEventVersionWithAlias = FlagPrintEventVersion + ", pev" FlagPrintFullyDetail = "print_full" FlagPrintFullyDetailWithAlias = FlagPrintFullyDetail + ", pf" FlagPrintRawTime = "print_raw_time" FlagPrintRawTimeWithAlias = FlagPrintRawTime + ", prt" FlagPrintDateTime = "print_datetime" FlagPrintDateTimeWithAlias = FlagPrintDateTime + ", pdt" FlagPrintMemo = "print_memo" FlagPrintMemoWithAlias = FlagPrintMemo + ", pme" FlagPrintJSON = "print_json" FlagPrintJSONWithAlias = FlagPrintJSON + ", pjson" FlagDescription = "description" FlagDescriptionWithAlias = FlagDescription + ", desc" FlagOwnerEmail = "owner_email" FlagOwnerEmailWithAlias = FlagOwnerEmail + ", oe" FlagRetentionDays = "retention" FlagRetentionDaysWithAlias = FlagRetentionDays + ", rd" FlagEmitMetric = "emit_metric" FlagEmitMetricWithAlias = FlagEmitMetric + ", em" FlagArchivalStatus = "archival_status" FlagArchivalStatusWithAlias = FlagArchivalStatus + ", as" FlagArchivalBucketName = "bucket" FlagArchivalBucketNameWithAlias = FlagArchivalBucketName + ", ab" FlagName = "name" FlagNameWithAlias = FlagName + ", n" FlagOutputFilename = "output_filename" FlagOutputFilenameWithAlias = FlagOutputFilename + ", of" FlagQueryType = "query_type" FlagQueryTypeWithAlias = FlagQueryType + ", qt" FlagShowDetail = "show_detail" FlagShowDetailWithAlias = FlagShowDetail + ", sd" FlagActiveClusterName = "active_cluster" FlagActiveClusterNameWithAlias = FlagActiveClusterName + ", ac" FlagClusters = "clusters" FlagClustersWithAlias = FlagClusters + ", cl" FlagDomainData = "domain_data" FlagDomainDataWithAlias = FlagDomainData + ", dmd" FlagEventID = "event_id" FlagEventIDWithAlias = FlagEventID + ", eid" FlagActivityID = "activity_id" FlagActivityIDWithAlias = FlagActivityID + ", aid" FlagMaxFieldLength = "max_field_length" FlagMaxFieldLengthWithAlias = FlagMaxFieldLength + ", maxl" FlagSecurityToken = "security_token" FlagSecurityTokenWithAlias = FlagSecurityToken + ", st" FlagSkipErrorMode = "skip_errors" FlagSkipErrorModeWithAlias = FlagSkipErrorMode + ", serr" FlagHeadersMode = "headers" FlagHeadersModeWithAlias = FlagHeadersMode + ", he" FlagMessageType = "message_type" FlagMessageTypeWithAlias = FlagMessageType + ", mt" FlagURL = "url" FlagMuttleyDestination = "muttely_destination" FlagMuttleyDestinationWithAlias = FlagMuttleyDestination + ", muttley" FlagIndex = "index" FlagBatchSize = "batch_size" FlagBatchSizeWithAlias = FlagBatchSize + ", bs" FlagMemoKey = "memo_key" FlagMemo = "memo" FlagMemoFile = "memo_file" FlagAddBadBinary = "add_bad_binary" FlagRemoveBadBinary = "remove_bad_binary" FlagResetType = "reset_type" FlagResetPointsOnly = "reset_points_only" FlagResetBadBinaryChecksum = "reset_bad_binary_checksum" )
Flags used to specify cli command line arguments
const ( // Version is the controlled version string. It should be updated every time // before we release a new version. Version = "0.6.2" )
Variables ¶
This section is empty.
Functions ¶
func AdminCatIndices ¶ added in v0.5.3
AdminCatIndices cat indices for ES cluster
func AdminDeleteWorkflow ¶ added in v0.5.0
AdminDeleteWorkflow describe a new workflow execution for admin
func AdminDescribeHistoryHost ¶ added in v0.3.13
AdminDescribeHistoryHost describes history host
func AdminDescribeTaskList ¶ added in v0.5.7
AdminDescribeTaskList displays poller and status information of task list.
func AdminDescribeWorkflow ¶ added in v0.3.13
AdminDescribeWorkflow describe a new workflow execution for admin
func AdminGetDomainIDOrName ¶ added in v0.5.0
AdminGetDomainIDOrName map domain
func AdminGetShardID ¶ added in v0.5.0
AdminGetShardID get shardID
func AdminIndex ¶ added in v0.5.3
AdminIndex used to bulk insert message from kafka parse
func AdminKafkaParse ¶ added in v0.5.0
AdminKafkaParse parses the output of k8read and outputs replication tasks
func AdminMergeDLQ ¶ added in v0.5.0
AdminMergeDLQ publish replication tasks from DLQ or JSON file
func AdminPurgeTopic ¶ added in v0.5.0
AdminPurgeTopic is used to purge kafka topic
func AdminRereplicate ¶ added in v0.5.0
AdminRereplicate parses will re-publish replication tasks to topic
func AdminShowWorkflow ¶ added in v0.5.0
AdminShowWorkflow shows history
func CancelWorkflow ¶
CancelWorkflow cancels a workflow execution
func ColorEvent ¶ added in v0.3.11
func ColorEvent(e *s.HistoryEvent) string
ColorEvent takes an event and return string with color Event with color mapping rules:
Failed - red Timeout - yellow Canceled - magenta Completed - green Started - blue Others - default (white/black)
func CompleteActivity ¶ added in v0.5.7
CompleteActivity completes an activity
func DescribeTaskList ¶
DescribeTaskList show pollers info of a given tasklist
func DescribeWorkflow ¶ added in v0.3.11
DescribeWorkflow show information about the specified workflow execution
func DescribeWorkflowWithID ¶ added in v0.3.11
DescribeWorkflowWithID show information about the specified workflow execution
func ErrorAndExit ¶
ErrorAndExit print easy to understand error msg first then error detail in a new line
func FailActivity ¶ added in v0.5.7
FailActivity fails an activity
func GetHistory ¶
func GetHistory(ctx context.Context, workflowClient client.Client, workflowID, runID string) (*s.History, error)
GetHistory helper method to iterate over all pages and return complete list of history events
func HistoryEventToString ¶
func HistoryEventToString(e *s.HistoryEvent, printFully bool, maxFieldLength int) string
HistoryEventToString convert HistoryEvent to string
func ListAllWorkflow ¶ added in v0.3.11
ListAllWorkflow list all workflow executions based on filters
func ListWorkflow ¶
ListWorkflow list workflow executions based on filters
func ObserveHistory ¶ added in v0.3.11
ObserveHistory show the process of running workflow
func ObserveHistoryWithID ¶ added in v0.3.11
ObserveHistoryWithID show the process of running workflow
func QueryWorkflowUsingStackTrace ¶
QueryWorkflowUsingStackTrace query workflow execution using __stack_trace as query type
func ResetInBatch ¶ added in v0.5.8
ResetInBatch resets workflow in batch
func ResetWorkflow ¶ added in v0.5.2
ResetWorkflow reset workflow
func RunWorkflow ¶
RunWorkflow starts a new workflow execution and print workflow progress and result
func SetFactory ¶ added in v0.5.0
func SetFactory(factory ClientFactory)
SetFactory is used to set the ClientFactory global
func SetRequiredDomainDataKeys ¶ added in v0.3.14
func SetRequiredDomainDataKeys(keys []string)
SetRequiredDomainDataKeys will set requiredDomainDataKeys
func ShowHistory ¶
ShowHistory shows the history of given workflow execution based on workflowID and runID.
func ShowHistoryWithWID ¶
ShowHistoryWithWID shows the history of given workflow with workflow_id
func SignalWorkflow ¶
SignalWorkflow signals a workflow execution
func StartWorkflow ¶
StartWorkflow starts a new workflow execution
func TerminateWorkflow ¶
TerminateWorkflow terminates a workflow execution
Types ¶
type ClientFactory ¶ added in v0.5.0
type ClientFactory interface { ClientFrontendClient(c *cli.Context) clientFrontend.Interface ServerFrontendClient(c *cli.Context) serverFrontend.Interface ServerAdminClient(c *cli.Context) serverAdmin.Interface }
ClientFactory is used to construct rpc clients
func NewClientFactory ¶ added in v0.5.0
func NewClientFactory() ClientFactory
NewClientFactory creates a new ClientFactory
type ClustersConfig ¶ added in v0.5.0
type ClustersConfig struct {
Clusters map[string]messaging.ClusterConfig
}
ClustersConfig describes the kafka clusters
type JSONHistorySerializer ¶
type JSONHistorySerializer struct{}
JSONHistorySerializer is used to encode history event in JSON
func (*JSONHistorySerializer) Deserialize ¶
func (j *JSONHistorySerializer) Deserialize(data []byte) (*s.History, error)
Deserialize deserializes history