Skip to content

Latest commit

 

History

History
137 lines (110 loc) · 5.44 KB

README.md

File metadata and controls

137 lines (110 loc) · 5.44 KB
Raw

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 ... with docker 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

  1. Tasklist name (--tl),
  2. Workflow type (--wt),
  3. 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.

  • 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.