Command Examples

CLIrrus currently support a number of commands.

• version:

  Print the installed Cirrus CLI version.

  cirrus version
  

• list-deployments:

  Return a list of all named cirrus deployments available for interacting with by pulling deployments available in AWS parameter store. Defaults to looking in the region used in AWS SSO login. Names returned here will be the name strings needed to run commands on a specific deployment.

  cirrus list-deployments
  

• manage (mgmt):

  A wrapper for commands to interact with a specific named deployment

  cirrus mgmt DEPLOYMENT_NAME COMMAND
  

• payload:

  a wrapper for commands for working with payloads.

  cirrus payload COMMAND
  

Manage commands

• call:

  Call a new command with the deployment environment variables loaded

  cirrus mgmt name-dev call ls
  

• exec:

  Run an executable with the deployment specific environment variables loaded into the local environment

  cirrus mgmt name-dev exec "bash" "hello_env_var_world.sh"
  

• get-execution:

  Get a workflow execution using its ARN or its payload-id

  cirrus mgmt name-dev get-execution --payload-id sar/workflow-test/example-01_2024-10-31-06-05-10
  
  cirrus mgmt name-dev get-execution --arn arn:aws:states:us-west-2:000000000011:execution:fd-name-dev-cirrus-project:c123456789-b19292-999
  

• get-execution-input:

  Get a workflow execution’s input payload using ARN or payload-id

  cirrus mgmt name-dev get-execution-input --arn arn:aws:states:us-west-2:000000000011:execution:fd-name-dev-cirrus-project:c123456789-b19292-999
  
  cirrus mgmt name-dev get-execution-input --payload-id sar/workflow-test/example-01_2024-10-31-06-05-10
  

• get-execution-output:

  Get a workflow execution’s output payload using payload-id or ARN

  cirrus mgmt name-dev get-execution-output --payload-id sar/workflow-test/example-01_2024-10-31-06-05-10
  
  cirrus mgmt name-dev get-execution-output --arn arn:aws:states:us-west-2:000000000011:execution:fd-name-dev-cirrus-project:c123456789-b19292-999
  

• get-workflow-definition:

  Get a workflow’s state machine ASL definition using the workflow name

  cirrus mgmt name-dev get-workflow-definition test
  

• get-execution-events:

  Get a workflow execution’s event history using its ARN or its input payload ID

  cirrus mgmt name-dev get-execution-events --payload-id sar/workflow-test/example-01_2024-10-31-06-05-10
  
  cirrus mgmt name-dev get-execution-events --arn arn:aws:states:us-west-2:000000000011:execution:fd-name-dev-cirrus-project:c123456789-b19292-999
  
  cirrus mgmt name-dev get-execution-events --payload-id sar/workflow-test/example-01_2024-10-31-06-05-10 --with-log-metadata
  

• get-lambda-logs:

  Get CloudWatch logs for a Lambda invocation

  cirrus mgmt name-dev get-lambda-logs /aws/lambda/my-function abc123-request-id
  
  cirrus mgmt name-dev get-lambda-logs /aws/lambda/my-function abc123-request-id --limit 50
  
  cirrus mgmt name-dev get-lambda-logs /aws/lambda/my-function abc123-request-id --start-time 1699999999000 --end-time 1700000099000
  
  cirrus mgmt name-dev get-lambda-logs /aws/lambda/my-function abc123-request-id --next-token "pagination-token-here"
  

• get-batch-logs:

  Get CloudWatch logs for a Batch job

  cirrus mgmt name-dev get-batch-logs my-job-log-stream
  
  cirrus mgmt name-dev get-batch-logs my-job-log-stream --log-group /aws/batch/custom
  
  cirrus mgmt name-dev get-batch-logs my-job-log-stream --limit 50 --next-token "pagination-token-here"
  

• get-input-payload:

  Get an input payload from S3 using its ID

  cirrus mgmt name-dev get-input-payload sar/workflow-test/example-01_2024-10-31-06-05-10
  

• get-output-payload:

  Get an output payload from S3 for an input payload ID

  cirrus mgmt name-dev get-output-payload sar/workflow-test/example-01_2024-10-31-06-05-10
  

• get-state:

  Get the stateDB record for a payload ID

  cirrus mgmt name-dev get-state sar/workflow-test/example-01_2024-10-31-06-05-10
  

• invoke-lambda:

  Invoke lambda with event (from stdin) and specifying by name which lambda to invoke

  <payload.json cirrus mgmt name-dev invoke-lambda process
  

• list-lambdas:

  List all lambda functions available in a given deployment

  cirrus mgmt name-dev list-lambdas
  

• process:

  Enqueue a payload (from stdin) for processing

  <payload.json cirrus mgmt name-dev process
  

• run-workflow:

  Pass a payload (from stdin) off to a deployment, wait for the workflow to finish, and retrieve and return its output payload

  <payload.json cirrus mgmt name-dev run-workflow
  

• show:

  Show a deployment configuration’s environment variables available in the parameter store

  cirrus mgmt name-dev show
  

• template-payload:

  Template a payload using a deployment’s environment variables and ‘$’ based substitution

  <payload.json cirrus mgmt name-dev template-payload --var EXAMPLE_VAR VALUE
  

• get-input-payloads:

  Bulk retrieve payloads as NDJSON. Can be filtered on fields available in StateDB - ‘collections-workflow’, ‘state’, ‘since’, ‘limit’, ‘error-prefix’. Output may be piped into additional commands to rerun payloads using the ‘rerun’ flag which alters the payload to allow rerunning.

  Piping with xargs to resubmit failed workflows:

  cirrus mgmt name-dev get-input-payloads --collections-workflow "sar-test_flow" --state "FAILED" --since "10 d" --rerun | xargs -0 -L 1 echo |  cirrus mgmt name-dev process
  

• query:

  Query the StateDB for records matching the supplied filters and return the raw StateDB records as NDJSON. Accepts the same filter options as get-input-payloads (--collections-workflow, --state, --since, --limit, --error-prefix) but returns state records directly instead of fetching input payloads from S3. Useful for inspecting StateDB entries or piping into other tools.

  cirrus mgmt name-dev query --collections-workflow "sar-test_workflow" --state "FAILED" --since "1 d"
  

• migrate:

  Migrate a deployment’s StateDB and payload bucket from the pre-v2 schema to the v2 schema. This performs a full DynamoDB table scan and updates each record in place while also copying existing input payloads (and, for recent executions, fetching output payloads from Step Functions history) into the new payload bucket layout. The operation is idempotent and may be re-run safely.

  Supported options:

  • --dry-run: preview all DynamoDB and S3 changes without writing anything.

  • --since-days INT: cutoff (in days) for fetching Step Functions outputs for legacy COMPLETED records. Defaults to 90, matching the default Step Functions history retention.

  Run this after deploying a v2 release of Cirrus to bring existing state records and payload objects in line with the new schema:

  cirrus mgmt name-dev migrate --dry-run
  cirrus mgmt name-dev migrate
  

Payload commands

• get-id:

  Get/generate an ID for a given payload

  <payload.json cirrus payload get-id
  

• template:

  Template a payload (from stdin) with user supplied variables with ‘$’ based substitution

  <payload.json cirrus payload template --var EXAMPLE_VAR VALUE
  

• validate:

  Validate an input payload (from stdin) is a valid cirrus payload

  <payload.json cirrus payload validate