README
¶
What
Cadence CLI provide an command-line tool for users to perform various tasks on Cadence.
Users can perform operations like register, update and describe on domain;
also start workflow, show workflow history, signal workflow ... and many other tasks.
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
to view help message. There are some top level commands and global options.
Run ./cadence domain
to view help message about operations on domain
Run ./cadence workflow
to view help message about operations on workflow
Run ./cadence tasklist
to view help message about operations on tasklist
(./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
Tips:
to avoid repeated input global option domain, user can export domain-name in environment variable CADENCE_CLI_DOMAIN.
export CADENCE_CLI_DOMAIN=samples-domain
# then just run commands without --domain flag, like
./cadence domain desc
Workflow operation examples
(The following examples assume you already export CADENCE_CLI_DOMAIN environment variable as Tips 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 it takes a string as input, so there is the -i '"cadence"'
. Single quote ''
is used to wrap input as json.
Note: you need to start 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, seperate 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}'
Workflow start
command is similar to run
command and takes same flag options. But it just start the workflow and immediately return workflow_id and run_id.
User need to run show
to view workflow history/progress.
Re-use the same workflow id when starting/running workflow
Use option --workflowidreusepolicy
or --wrp
to configure workflow id re-use policy.
Option 0 AllowDuplicateFailedOnly: Allow start a workflow execution using the same workflow ID when workflow not running, and the last execution close state is in [terminated, cancelled, timeouted, failed].
Option 1 AllowDuplicate: Allow start a workflow execution using the same workflow ID when workflow not running.
Option 2 RejectDuplicate: Do not allow start a workflow execution using the same workflow ID at all.
# 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 descibe -w 3ea6b242-b23c-4279-bb13-f215661b4717 -r 866ae14c-88cf-4f1e-980f-571e031d71b0
# a shortcut of this is (without -w -r flag)
./cadence workflow descibeid 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 descibe -w 3ea6b242-b23c-4279-bb13-f215661b4717
# a shortcut of this is
./cadence workflow descibeid 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
Terminate a running workflow execution will record WorkflowExecutionTerminated event as closing event in the history. No more decision task will be scheduled for terminated workflow execution.
Cancel a running workflow execution will record WorkflowExecutionCancelRequested event in the history, and a new decision task will be scheduled. Workflow has a chance to do some clean up work after cancellation.
Documentation
¶
Index ¶
- Constants
- func AdminDeleteWorkflow(c *cli.Context)
- func AdminDescribeDomain(c *cli.Context)
- func AdminDescribeHistoryHost(c *cli.Context)
- func AdminDescribeWorkflow(c *cli.Context)
- func AdminGetDomainIDOrName(c *cli.Context)
- func AdminGetShardID(c *cli.Context)
- func AdminKafkaParse(c *cli.Context)
- func AdminMergeDLQ(c *cli.Context)
- func AdminPurgeTopic(c *cli.Context)
- func AdminRegisterDomain(c *cli.Context)
- func AdminRereplicate(c *cli.Context)
- func AdminShowWorkflow(c *cli.Context)
- func AdminUpdateDomain(c *cli.Context)
- func CancelWorkflow(c *cli.Context)
- func ColorEvent(e *s.HistoryEvent) string
- 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 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 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" FlagInputTopic = "input_topic" FlagInputTopicWithAlias = FlagInputTopic + ", it" FlagHostFile = "host_file" FlagCluster = "cluster" FlagInputCluster = "input_cluster" FlagStartOffset = "start_offset" FlagTopic = "topic" FlagGroup = "group" 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" 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" FlagMaxFieldLength = "max_field_length" FlagMaxFieldLengthWithAlias = FlagMaxFieldLength + ", maxl" FlagSecurityToken = "security_token" FlagSecurityTokenWithAlias = FlagSecurityToken + ", st" FlagSkipErrorMode = "skip_errors" FlagSkipErrorModeWithAlias = FlagSkipErrorMode + ", serr" FlagHeadersMode = "headers" FlagHeadersModeWithAlias = FlagHeadersMode + ", he" )
* 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.5.8" )
Variables ¶
This section is empty.
Functions ¶
func AdminDeleteWorkflow ¶ added in v0.5.0
AdminDeleteWorkflow describe a new workflow execution for admin
func AdminDescribeDomain ¶ added in v0.5.0
AdminDescribeDomain updates a domain
func AdminDescribeHistoryHost ¶ added in v0.3.13
AdminDescribeHistoryHost describes history host
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 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 AdminRegisterDomain ¶ added in v0.5.0
AdminRegisterDomain register a domain
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 AdminUpdateDomain ¶ added in v0.5.0
AdminUpdateDomain updates a domain
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 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 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 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