Skip to content

Step Functions Commands

Inspect state machines, start executions, and pull execution logs.

Most commands take a state machine ARN rather than a name. Get it from list first.

Commands

stepfunctions describe

Get detailed information about a Step Functions state machine.

aws-cloud-utilities stepfunctions describe STATE_MACHINE_ARN [OPTIONS]
Option Value Description
--show-definition flag Show the state machine definition
--output-file TEXT Output file for state machine details (supports .json, .yaml)

stepfunctions execute

Start an execution of a Step Functions state machine.

aws-cloud-utilities stepfunctions execute STATE_MACHINE_ARN [OPTIONS]
Option Value Description
--input TEXT JSON input for the execution (default: {})
--name TEXT Name for the execution (auto-generated if not provided)
--wait flag Wait for execution to complete
--timeout INTEGER Timeout in seconds for execution wait (default: 300)

stepfunctions list

List all Step Functions state machines.

aws-cloud-utilities stepfunctions list [OPTIONS]
Option Value Description
--region TEXT AWS region to list state machines from (default: current region)
--all-regions flag List state machines from all regions
--output-file TEXT Output file for state machines list (supports .json, .yaml, .csv)

stepfunctions list-executions

List executions of a Step Functions state machine.

aws-cloud-utilities stepfunctions list-executions STATE_MACHINE_ARN [OPTIONS]
Option Value Description
--status RUNNING | SUCCEEDED | FAILED | TIMED_OUT | ABORTED Filter executions by status
--max-results INTEGER Maximum number of executions to list (default: 10)
--output-file TEXT Output file for executions list (supports .json, .yaml, .csv)

stepfunctions logs

Show CloudWatch logs for a Step Functions execution.

aws-cloud-utilities stepfunctions logs EXECUTION_ARN LOG_GROUP [OPTIONS]
Option Value Description
--lines INTEGER Maximum number of log lines to retrieve (default: 100)
--output-file TEXT Output file for logs (supports .txt, .json)

Examples

# State machines
aws-cloud-utilities stepfunctions list
aws-cloud-utilities stepfunctions list --all-regions --output-file state-machines.json

# Detail, including the ASL definition
aws-cloud-utilities stepfunctions describe \
    arn:aws:states:us-east-1:123456789012:stateMachine:MyMachine --show-definition

# Start an execution and wait for it
aws-cloud-utilities stepfunctions execute \
    arn:aws:states:us-east-1:123456789012:stateMachine:MyMachine \
    --input '{"key": "value"}' --wait --timeout 600

# Named execution
aws-cloud-utilities stepfunctions execute \
    arn:aws:states:us-east-1:123456789012:stateMachine:MyMachine --name nightly-run

# Recent executions, failures only
aws-cloud-utilities stepfunctions list-executions \
    arn:aws:states:us-east-1:123456789012:stateMachine:MyMachine \
    --status FAILED --max-results 50

# Logs for one execution
aws-cloud-utilities stepfunctions logs \
    arn:aws:states:us-east-1:123456789012:execution:MyMachine:abc123 \
    /aws/vendedlogs/states/MyMachine --lines 500

logs takes two arguments

stepfunctions logs needs both the execution ARN and the CloudWatch log group the state machine writes to, in that order. It cannot infer the log group, because logging configuration is optional and the destination is arbitrary. Find it with describe, or list candidates:

aws-cloud-utilities logs list-groups | grep vendedlogs

Notes

--input takes a JSON string and defaults to {}. Quote it for your shell.

--wait blocks until the execution finishes or --timeout seconds elapse; the default timeout is 300 seconds, which is shorter than many workflows.