Workflow Commands

The workflow command group provides operations for managing workflow executions throughout their lifecycle.

Command Overview

cadence workflow [command] [flags]

Short alias: wf

cadence wf list  # Same as: cadence workflow list

Starting Workflows

start

Start a new workflow execution without waiting for completion.

cadence workflow start \
  --workflow_type MyWorkflow \
  --tasklist my-tasklist \
  --execution_timeout 3600 \
  --input '{"name": "value"}'

--workflow_type

string

required

Name of the workflow type to execute

--tasklist

string

required

Task list name for workflow execution

--workflow_id

string

Unique workflow ID. Auto-generated if not provided

--input

string

Workflow input as JSON string

--execution_timeout

int

default:"0"

Workflow execution timeout in seconds (0 = no timeout)

--decision_timeout

int

default:"10"

Decision task timeout in seconds

--cron

string

Cron schedule for periodic workflow execution

--workflowidreusepolicy

string

Workflow ID reuse policy: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate

run

Start a workflow and wait for completion, showing progress.

cadence workflow run \
  --workflow_type MyWorkflow \
  --tasklist my-tasklist \
  --input '{"count": 10}'

Same parameters as start, plus automatically shows workflow result.

Querying Workflows

list

List open or closed workflow executions.

cadence workflow list

# List closed workflows
cadence workflow list --open=false

# Filter by workflow type
cadence workflow list --workflow_type MyWorkflow

# Custom query
cadence workflow list --query "WorkflowType='MyWorkflow' AND StartTime > '2024-01-01'"

--open

bool

default:"true"

List open workflows (true) or closed workflows (false)

--pagesize

int

default:"10"

Number of results per page

--workflow_type

string

Filter by workflow type

--query

string

SQL-like query for advanced filtering

listall

List all workflows without pagination.

cadence workflow listall --query "WorkflowType='MyWorkflow'"

scan

Fast scan of workflow executions (requires ElasticSearch).

cadence workflow scan --query "WorkflowType='MyWorkflow'"

The scan command is faster than listall but results are not sorted. Requires ElasticSearch to be enabled on the Cadence server.

count

Count workflow executions matching a query.

cadence workflow count --query "WorkflowType='MyWorkflow' AND CloseStatus='Completed'"

Inspecting Workflows

describe

Show detailed information about a workflow execution.

cadence workflow describe -w my-workflow-id

# With run ID for specific execution
cadence workflow describe -w my-workflow-id -r abc123

--workflow_id

string

required

Workflow ID to describe

--run_id

string

Run ID for specific execution (defaults to current/latest)

describeid

Shortcut for describe using positional arguments.

cadence workflow describeid my-workflow-id

# With run ID
cadence workflow describeid my-workflow-id abc123

show

Display workflow execution history.

cadence workflow show -w my-workflow-id

# Save history to file
cadence workflow show -w my-workflow-id --output_filename history.json

# Print with timestamps
cadence workflow show -w my-workflow-id --print_datetime

# Show specific event
cadence workflow show -w my-workflow-id --event_id 5

--print_datetime

bool

Print timestamps for events

--print_raw_time

bool

Print raw Unix timestamps

--output_filename

string

Save history to file

--print_full

bool

Print full event details

--event_id

int

Show specific event by ID

showid

Shortcut for show using positional arguments.

cadence workflow showid my-workflow-id

observe

Continuously watch workflow execution progress.

cadence workflow observe -w my-workflow-id

Shows real-time updates as the workflow progresses.

Signaling Workflows

signal

Send a signal to a running workflow.

cadence workflow signal \
  -w my-workflow-id \
  --signal_name UpdateConfig \
  --input '{"setting": "value"}'

--workflow_id

string

required

Target workflow ID

--signal_name

string

required

Name of the signal

--input

string

Signal payload as JSON

--run_id

string

Specific run ID (defaults to current)

signalwithstart

Signal an existing workflow or start a new one if it doesn’t exist.

cadence workflow signalwithstart \
  -w my-workflow-id \
  --workflow_type MyWorkflow \
  --tasklist my-tasklist \
  --signal_name ProcessData \
  --input '{"data": "value"}'

Combines parameters from both start and signal commands.

Querying Workflow State

query

Query workflow state without affecting execution.

cadence workflow query \
  -w my-workflow-id \
  --query_type GetStatus

# With query arguments
cadence workflow query \
  -w my-workflow-id \
  --query_type GetDetails \
  --input '{"field": "name"}'

--query_type

string

required

Name of the query handler

--input

string

Query arguments as JSON

query-types

List available query types for a workflow.

cadence workflow query-types -w my-workflow-id

stack

Get workflow stack trace using the built-in __stack_trace query.

cadence workflow stack -w my-workflow-id

Stopping Workflows

cancel

Gracefully stop a workflow, allowing cleanup.

cadence workflow cancel -w my-workflow-id

# With reason
cadence workflow cancel -w my-workflow-id --reason "User requested cancellation"

--reason

string

Reason for cancellation

Cancel allows the workflow to run cleanup code. Use terminate for immediate stop.

terminate

Force-stop a workflow without cleanup.

cadence workflow terminate -w my-workflow-id

# With reason
cadence workflow terminate -w my-workflow-id --reason "Invalid state detected"

Terminate immediately stops the workflow without running cleanup logic. Use cancel for graceful shutdown.

Workflow Reset

reset

Reset a workflow to a specific event.

# Reset to specific event ID
cadence workflow reset \
  -w my-workflow-id \
  --event_id 15 \
  --reason "Recovering from bad deployment"

# Reset to last decision
cadence workflow reset \
  -w my-workflow-id \
  --reset_type LastDecisionCompleted \
  --reason "Reprocessing from checkpoint"

--event_id

string

Event ID to reset to (exclusive)

--reset_type

string

Reset type: FirstDecisionCompleted, LastDecisionCompleted, BadBinary, DecisionCompletedTime

--reason

string

required

Reason for reset (required for tracking)

--reset_bad_binary_checksum

string

Binary checksum for BadBinary reset type

--earliest_time

string

Earliest time for DecisionCompletedTime reset. Formats: RFC3339, Unix nano, or time range (e.g., ‘15m’)

--skip_signal_reapply

bool

Skip reapplying signals after reset point

reset-batch

Reset multiple workflows from a file or query.

# From file
cadence workflow reset-batch \
  --input_file workflows.txt \
  --reset_type LastDecisionCompleted \
  --reason "Bulk recovery"

# From query
cadence workflow reset-batch \
  --query "WorkflowType='MyWorkflow' AND CloseStatus='Failed'" \
  --reset_type LastDecisionCompleted \
  --reason "Recovering failed workflows"

--input_file

string

File with workflow IDs (one per line, format: workflowID [runID])

--query

string

Query to select workflows for reset

--parallelism

int

default:"1"

Number of parallel reset operations

--dry_run

bool

Preview reset without executing

restart

Restart a completed workflow execution.

cadence workflow restart -w my-workflow-id

refresh-tasks

Refresh workflow tasks to resume progress.

cadence workflow refresh-tasks -w my-workflow-id

Activity Operations

activity complete

Manually complete an activity.

cadence workflow activity complete \
  -w my-workflow-id \
  --activity_id my-activity \
  --result '{"status": "done"}'

activity fail

Manually fail an activity.

cadence workflow activity fail \
  -w my-workflow-id \
  --activity_id my-activity \
  --reason "External system unavailable"

Batch Operations

See the Batch Commands page for batch operation details.

Examples

Start a workflow with cron schedule

cadence workflow start \
  --workflow_type DailyReport \
  --tasklist reports \
  --cron "0 9 * * *" \
  --input '{"report_type": "daily"}'

Query workflow status

cadence workflow query \
  -w order-12345 \
  --query_type GetOrderStatus

Reset failed workflows

cadence workflow reset-batch \
  --query "CloseStatus='Failed' AND StartTime > '2024-01-01'" \
  --reset_type LastDecisionCompleted \
  --reason "Recovering from outage" \
  --parallelism 10

Watch workflow progress

cadence workflow observe -w long-running-workflow

Output Examples

Workflow List

  WORKFLOW TYPE  |  WORKFLOW ID  |  RUN ID  |  START TIME  |  EXECUTION TIME
  MyWorkflow     |  wf-001       |  abc123  |  2024-01-15  |  2m 30s
  MyWorkflow     |  wf-002       |  def456  |  2024-01-15  |  1m 45s

Workflow Describe

{
  "executionConfiguration": {
    "taskList": {"name": "my-tasklist"},
    "executionStartToCloseTimeoutSeconds": 3600,
    "taskStartToCloseTimeoutSeconds": 10
  },
  "workflowExecutionInfo": {
    "execution": {
      "workflowId": "my-workflow-id",
      "runId": "abc123"
    },
    "type": {"name": "MyWorkflow"},
    "startTime": "2024-01-15T10:00:00Z",
    "closeStatus": "COMPLETED"
  }
}

Next Steps

Domain Commands

Configure workflow domains

Batch Commands

Bulk workflow operations

Task List Commands

Monitor task lists

Workflow Concepts

Learn about workflows

Overview

Commands

​Command Overview

​Starting Workflows

​start

​run

​Querying Workflows

​list

​listall

​scan

​count

​Inspecting Workflows

​describe

​describeid

​show

​showid

​observe

​Signaling Workflows

​signal

​signalwithstart

​Querying Workflow State

​query

​query-types

​stack

​Stopping Workflows

​cancel

​terminate

​Workflow Reset

​reset

​reset-batch

​restart

​refresh-tasks

​Activity Operations

​activity complete

​activity fail

​Batch Operations

​Examples

​Start a workflow with cron schedule

​Query workflow status

​Reset failed workflows

​Watch workflow progress

​Output Examples

​Workflow List

​Workflow Describe

​Next Steps

Domain Commands

Batch Commands

Task List Commands

Workflow Concepts

Build docs developers (and LLMs) love

Command Overview

Starting Workflows

start

run

Querying Workflows

list

listall

scan

count

Inspecting Workflows

describe

describeid

show

showid

observe

Signaling Workflows

signal

signalwithstart

Querying Workflow State

query

query-types

stack

Stopping Workflows

cancel

terminate

Workflow Reset

reset

reset-batch

restart

refresh-tasks

Activity Operations

activity complete

activity fail

Batch Operations

Examples

Start a workflow with cron schedule

Query workflow status

Reset failed workflows

Watch workflow progress

Output Examples

Workflow List

Workflow Describe

Next Steps