How to Use AWS CLI with Step Functions

Summary:

• Master essential AWS CLI commands for Step Functions including create-state-machine, start-execution, and describe-state-machine with practical syntax examples.
• Implement advanced deployment strategies using versioning, aliases, and canary deployments to achieve zero-downtime releases.
• Understand the critical differences between standard and express workflows to optimize cost and performance for your specific use case.
• Leverage the TestState API and Step Functions Local for robust testing workflows before production deployment.

Managing serverless orchestration through a web console works fine until you need to deploy state machines across multiple environments, automate rollbacks during incidents, or integrate workflow management into your CI/CD pipeline. At that point, the AWS CLI becomes your primary interface for Step Functions. It transforms manual operations into scriptable, repeatable, and auditable processes. This guide walks you through the complete CLI toolkit for Step Functions, from foundational commands to advanced deployment patterns that separate production-ready implementations from tutorial-level experiments.

The following diagram illustrates the relationship between AWS CLI commands and the Step Functions service architecture. It shows how CLI operations map to the underlying API endpoints.

Overview of CLI and state machine workflows

AWS Step Functions provides two distinct workflow types. Understanding their characteristics determines which CLI commands and execution patterns you will use. Standard workflows offer exactly-once execution semantics with a maximum duration of one year, making them suitable for long-running processes like order fulfillment or ETL pipelines. Express workflows deliver at-least-once execution with a five-minute maximum duration, optimized for high-volume event processing where throughput matters more than execution guarantees.

The choice between standard and express workflows affects not just your application architecture but also your CLI interaction patterns. Standard workflows use asynchronous execution by default through the start-execution command, requiring subsequent polling or callback mechanisms to retrieve results. Express workflows support synchronous execution via start-sync-execution, returning results directly in the CLI response. This distinction becomes critical when designing automation scripts that depend on execution outcomes.

Before diving into specific commands, ensure your CLI environment is properly configured with appropriate IAM permissions. The states:* permission set provides full Step Functions access. However, production environments should follow least-privilege principles by granting only necessary actions like states:StartExecution or states:DescribeStateMachine. With your environment prepared, the next section covers the essential commands that form the foundation of CLI-based workflow management.

Key AWS CLI commands for Step Functions

The Step Functions CLI command family operates under the aws stepfunctions namespace, providing comprehensive control over state machine lifecycle management. Mastering these commands enables you to automate deployments, monitor executions, and troubleshoot failures without leaving your terminal. The following subsections break down the most critical operations you will perform regularly.

Creating and managing state machines

The create-state-machine command establishes new workflow definitions in your AWS account. This command requires three essential parameters. You need a unique name, the Amazon States Language definition, and an IAM role ARN that grants the state machine permission to invoke integrated services.

aws stepfunctions create-state-machine \
  --name "OrderProcessingWorkflow" \
  --definition file://state-machine-definition.json \
  --role-arn arn:aws:iam::123456789012:role/StepFunctionsExecutionRole \
  --type STANDARD \
  --logging-configuration level=ALL,includeExecutionData=true,destinations=[{cloudWatchLogsLogGroup={logGroupArn=arn:aws:logs:us-east-1:123456789012:log-group:/aws/stepfunctions/OrderProcessing}}]

The --type parameter accepts either STANDARD or EXPRESS, defaulting to STANDARD if omitted. Including the --logging-configuration parameter from the start saves debugging time later by ensuring execution history flows to CloudWatch Logs. After creation, use describe-state-machine to verify the configuration and retrieve the state machine ARN for subsequent operations.

Updating existing state machines uses the update-state-machine command, which accepts the state machine ARN and any parameters you wish to modify. Unlike creation, updates do not require all parameters, only those being changed. This command returns immediately but the update propagates asynchronously, so subsequent executions may briefly use the previous definition.

Starting and monitoring executions

Launching workflow executions from the CLI provides the foundation for automation and integration testing. The execution commands differ based on workflow type and whether you need synchronous results.

For standard workflows, use the asynchronous pattern:

aws stepfunctions start-execution \
  --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow \
  --name "order-12345-$(date +%s)" \
  --input '{"orderId": "12345", "customerId": "cust-789"}'

The --name parameter must be unique within a 90-day window for the same state machine. Appending timestamps or UUIDs prevents naming collisions in automated scenarios. The command returns an execution ARN immediately, which you then use with describe-execution to poll for completion status.

Express workflows support synchronous execution when you need immediate results:

aws stepfunctions start-sync-execution \
  --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:PaymentValidation \
  --input '{"amount": 99.99, "currency": "USD"}'

Monitoring execution status across multiple workflows requires the list-executions command with filtering capabilities:

aws stepfunctions list-executions \
  --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow \
  --status-filter FAILED \
  --max-items 50

The --status-filter parameter accepts RUNNING, SUCCEEDED, FAILED, TIMED_OUT, or ABORTED values. Combining this with the --query parameter enables sophisticated filtering for operational dashboards and alerting scripts. Understanding these execution patterns prepares you for the advanced deployment strategies covered next.

Advanced workflows with versioning, aliases, and canary deployments

Production deployments demand more than simple create-and-update cycles. Step Functions versioning and alias features enable sophisticated deployment strategies that minimize risk and provide instant rollback capabilities. These features, accessible entirely through CLI commands, transform how teams manage workflow releases.

Publishing and managing versions

A version represents an immutable snapshot of your state machine definition at a specific point in time. Publishing versions creates stable reference points that cannot be modified, ensuring that running executions complete with the exact definition they started with.

aws stepfunctions publish-state-machine-version \
  --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow \
  --description "Release 2.3.1 - Added retry logic for payment failures"

This command returns a version ARN that includes a numeric suffix, such as :1 or :2. The description parameter, while optional, proves invaluable for tracking which changes each version contains. List all versions using:

aws stepfunctions list-state-machine-versions \
  --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow

Version management follows a clear lifecycle pattern:

• Development: Update the state machine definition iteratively without publishing versions.
• Release: Publish a version when the definition reaches a stable, tested state.
• Deployment: Route traffic to the new version through aliases.
• Cleanup: Delete old versions that are no longer needed using delete-state-machine-version.

Configuring aliases for traffic management

Aliases provide named references to specific versions, enabling traffic routing without changing client configurations. Think of aliases as DNS records for your state machine versions. They allow you to redirect execution traffic by updating the alias rather than modifying calling applications.

aws stepfunctions create-state-machine-alias \
  --name "production" \
  --routing-configuration stateMachineVersionArn=arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow:3,weight=100

The routing configuration supports weighted distribution across multiple versions, enabling canary deployments and gradual rollouts. Consider the following traffic shifting strategy for a new release:

# Day 1: 5% canary
aws stepfunctions update-state-machine-alias \
  --state-machine-alias-arn arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow:production \
  --routing-configuration '[{"stateMachineVersionArn":"arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow:2","weight":95},{"stateMachineVersionArn":"arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow:3","weight":5}]'

# Day 2: 30% if no errors
aws stepfunctions update-state-machine-alias \
  --state-machine-alias-arn arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow:production \
  --routing-configuration '[{"stateMachineVersionArn":"arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow:2","weight":70},{"stateMachineVersionArn":"arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow:3","weight":30}]'

Rollback becomes a single command when issues arise:

aws stepfunctions update-state-machine-alias \
  --state-machine-alias-arn arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow:production \
  --routing-configuration stateMachineVersionArn=arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow:2,weight=100

This deployment infrastructure provides the safety net needed for continuous delivery. However, catching issues before they reach production requires robust testing capabilities, which the next section addresses.

Testing and local development

Validating state machine behavior before deployment prevents costly production incidents. AWS provides two complementary testing approaches accessible through the CLI. The TestState API handles isolated state testing, while Step Functions Local enables complete workflow simulation.

Using the TestState API

The TestState API executes individual states in isolation, enabling targeted testing of specific workflow components without running the entire state machine. This capability proves particularly valuable for testing complex Choice states, error handling paths, or states with intricate input/output processing.

aws stepfunctions test-state \
  --definition '{"Type":"Task","Resource":"arn:aws:lambda:us-east-1:123456789012:function:ValidateOrder","End":true}' \
  --role-arn arn:aws:iam::123456789012:role/StepFunctionsExecutionRole \
  --input '{"orderId":"test-123","items":[{"sku":"ABC","quantity":2}]}' \
  --inspection-level DEBUG

The --inspection-level parameter controls the detail level of the response:

Before testing execution, validate your state machine definition syntax using the dedicated validation command:

aws stepfunctions validate-state-machine-definition \
  --definition file://state-machine-definition.json \
  --type STANDARD

This command catches syntax errors and structural issues without creating resources, making it ideal for pre-commit hooks in your development workflow.

Running Step Functions Local

Step Functions Local provides a Docker-based emulator that runs state machines entirely on your development machine. This approach eliminates cloud costs during development and enables testing without network connectivity.

Start the local environment using Docker:

docker run -p 8083:8083 amazon/aws-stepfunctions-local

Configure your CLI to target the local endpoint:

aws stepfunctions create-state-machine \
  --endpoint-url http://localhost:8083 \
  --name "LocalTestWorkflow" \
  --definition file://state-machine-definition.json \
  --role-arn arn:aws:iam::123456789012:role/PlaceholderRole

The following diagram shows how Step Functions Local integrates with mocked services for comprehensive local testing.

Step Functions Local supports mocked service integrations, allowing you to simulate Lambda responses, DynamoDB operations, and other AWS service calls without actual cloud resources. Configure mocks through a JSON file:

{
  "StateMachines": {
    "LocalTestWorkflow": {
      "TestCases": {
        "HappyPath": {
          "ValidateOrder": {"Return": {"statusCode": 200, "body": {"valid": true}}}
        }
      }
    }
  }
}

The combination of TestState API for targeted state validation and Step Functions Local for complete workflow testing creates a comprehensive testing strategy. These tools, combined with the deployment patterns discussed earlier, provide the foundation for reliable Step Functions operations.

Error handling and observability via CLI

Production workflows require robust error handling and comprehensive observability. The CLI provides commands for both configuring error handling within state machines and retrieving diagnostic information when failures occur.

Retrieve detailed execution history for failed workflows:

aws stepfunctions get-execution-history \
  --execution-arn arn:aws:states:us-east-1:123456789012:execution:OrderProcessingWorkflow:order-12345 \
  --reverse-order \
  --query "events[?type=='TaskFailed' || type=='ExecutionFailed']"

The --query parameter uses JMESPath syntax to filter results, extracting only failure-related events from potentially lengthy execution histories. For ongoing monitoring, combine list-executions with status filtering in scheduled scripts:

aws stepfunctions list-executions \
  --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow \
  --status-filter FAILED \
  --query "executions[?startDate>=\`$(date -d '1 hour ago' -Iseconds)\`]"

Enable X-Ray tracing during state machine creation or update for distributed tracing capabilities:

aws stepfunctions update-state-machine \
  --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:OrderProcessingWorkflow \
  --tracing-configuration enabled=true

This integration surfaces Step Functions execution data in AWS X-Ray service maps, enabling end-to-end visibility across distributed systems.

Conclusion

Effective AWS CLI usage with Step Functions transforms workflow management from manual console operations into automated, version-controlled processes. The commands covered in this guide provide the toolkit needed for production-grade serverless orchestration. This includes basic creation and execution as well as advanced versioning and alias-based deployments. The key differentiator between tutorial-level implementations and production systems lies in adopting versioning and alias patterns that enable safe deployments and instant rollbacks.

As Step Functions continues evolving with features like enhanced observability integrations and expanded service connectors, CLI proficiency becomes increasingly valuable. Teams that invest in CLI-based automation today position themselves to adopt new capabilities rapidly while maintaining the operational discipline that complex distributed systems demand. Start by implementing version-controlled state machine definitions and alias-based deployments in your next project. Then expand to comprehensive testing workflows using TestState and Step Functions Local.