Command Examples
================

CLIrrus currently support a number of commands.

- *version:*
    Print the installed Cirrus CLI version.

    .. code-block:: bash

        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.

    .. code-block:: bash

        cirrus list-deployments

- *manage (mgmt):*
    A wrapper for commands to interact with a specific named deployment

    .. code-block:: bash

        cirrus mgmt DEPLOYMENT_NAME COMMAND


- *payload:*
    a wrapper for commands for working with payloads.

    .. code-block:: bash

        cirrus payload COMMAND


Manage commands
---------------
- *call:*
    Call a new command with the deployment environment variables loaded

    .. code-block:: bash

        cirrus mgmt name-dev call ls

- *exec:*
    Run an executable with the deployment specific environment variables loaded into the local environment

    .. code-block:: bash

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

- *get-execution:*
    Get a workflow execution using its ARN or its payload-id

    .. code-block:: bash

        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

    .. code-block:: bash

        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

    .. code-block:: bash

        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

    .. code-block:: bash

        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

    .. code-block:: bash

        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

    .. code-block:: bash

        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

    .. code-block:: bash

        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

    .. code-block:: bash

        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

    .. code-block:: bash

        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

    .. code-block:: bash

        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

    .. code-block:: bash

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

- *list-lambdas*:
    List all lambda functions available in a given deployment

    .. code-block:: bash

        cirrus mgmt name-dev list-lambdas

- *process:*
    Enqueue a payload (from stdin) for processing

    .. code-block:: bash

        <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

    .. code-block:: bash

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

- *show:*
    Show a deployment configuration's environment variables available in the parameter store

    .. code-block:: bash

        cirrus mgmt name-dev show

- *template-payload:*
    Template a payload using a deployment's environment variables and '$' based substitution

    .. code-block:: bash

        <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:

    .. code-block:: bash

        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.

    .. code-block:: bash

        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:

    .. code-block:: bash

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

Payload commands
----------------

- *get-id:*
    Get/generate an ID for a given payload

    .. code-block:: bash

        <payload.json cirrus payload get-id

- *template:*
    Template a payload (from stdin) with user supplied variables with '$' based substitution

    .. code-block:: bash

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

- *validate:*
    Validate an input payload (from stdin) is a valid cirrus payload

    .. code-block:: bash

        <payload.json cirrus payload validate