alarm list

The stacktape alarm list command displays the current state of CloudWatch alarms for a deployed stack. Use it to check which alarms are firing, which are healthy, and when each alarm last changed state — without opening the AWS Console.

Usage

stacktape alarm list --stage prod --region eu-west-1

This queries CloudWatch alarms whose names start with the stack name and prints the matching alarms. Each alarm is mapped to its name, matched Stacktape resource (when identified), current state, metric, threshold, comparison operator, and last state change time. Alarms in the ALARM state also include the reason they triggered.

Filtering

Filter by resource

Use --resource-name to narrow results to alarms belonging to a single Stacktape resource. The resource name must match the key used in your Stacktape configuration.

stacktape alarm list --stage prod --region eu-west-1 --resource-name myApi

Filter by state

Use --state to show only alarms in a specific state. Accepted values are OK, ALARM, and INSUFFICIENT_DATA.

Show only alarms that are currently firing:

stacktape alarm list --stage prod --region eu-west-1 --state ALARM

Show only healthy alarms:

stacktape alarm list --stage prod --region eu-west-1 --state OK

You can combine both filters to check whether a specific resource has any firing alarms:

stacktape alarm list --stage prod --region eu-west-1 --resource-name myApi --state ALARM

Agent mode

Pass --agent for machine-readable output. For the alarm list command, agent mode emits a JSON object with an alarms array. Each entry contains the alarm's name, matched resource (if any), state, metric, threshold, comparison, lastUpdated, and (for alarms in the ALARM state) reason.

stacktape alarm list --stage prod --region eu-west-1 --agent

Flags reference

stacktape alarm listCLI options
-r, --regionrequired"us-east-2" | "us-east-1" | "us-west-1" | "us-west-2" | "ap-east-1" | "ap-south-1" | "ap-northeast-3" | "ap-northeast-2" | "ap-southeast-1" | "ap-southeast-2" | "ap-northeast-1" | "ca-central-1" | "eu-central-1" | "eu-west-1" | "eu-west-2" | "eu-west-3" | "eu-north-1" | "me-south-1" | "sa-east-1" | "af-south-1" | "eu-south-1"

AWS Region

The AWS region for the operation. For a list of available regions, see the AWS documentation.

Inside a project whose config declares region, the flag is optional and overrides the config.

-s, --stagerequiredstring

Stage

The stage for the operation (e.g., production, staging, dev-john). You can set a default stage using the defaults set command. Stage names use lowercase letters, numbers and dashes, with at least 2 characters. The project name, a dash and the stage form the CloudFormation stack name, which can have at most 128 characters. Stacktape shortens an AWS resource name that would be too long and adds a hash.

--aws-accountstring

AWS Account

The name of the AWS account to use for the operation. The account must first be connected in the Stacktape Console.

Without it, the account is chosen by --profile, AWS_PROFILE or AWS credentials in environment variables, then by your saved default, then by your organization's only connected account. --aws-account takes precedence over all of them, but AWS credentials in environment variables must then belong to that account.

-h, --helpstring

Show Help

If provided, the command will not execute and will instead print help information.

--log-level"info" | "debug" | "error"

Log Level

The level of logs to print to the console.

  • info: Basic information about the operation.
  • error: Only errors.
  • debug: Detailed information for debugging.
-p, --profilestring

AWS Profile

The AWS profile to use for the command. You can manage profiles using the aws-profile:* commands and set a default profile with defaults set.

For commands that use a connected AWS account, --profile (or AWS_PROFILE) selects the connected account the profile belongs to, unless --aws-account is set. The command fails if that account is not connected.

--projectstring

Project Name

The name of the Stacktape project for this operation.

Commands that target a stack take it from projectName in the project's config when the flag is absent.

--quietboolean

Quiet

Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.

--resource-namestring

Resource Name

The name of the resource as defined in your Stacktape configuration.

--statestring

Alarm State Filter

Filter alarms by state: OK, ALARM, or INSUFFICIENT_DATA.

alarm list FAQ

What alarms does this command show?

The alarm list command queries all CloudWatch alarms whose name starts with the stack name. In practice, this targets alarms associated with the Stacktape stack. It does not show alarms created outside of Stacktape unless they happen to share the stack name prefix. For details on configuring alarm rules, see Alarms.

What do the alarm states mean?

CloudWatch alarms have three states. OK means the metric is within the configured threshold. ALARM means the metric has breached the threshold for the required number of evaluation periods. INSUFFICIENT_DATA means there is not enough data to evaluate the alarm — this is common for newly created alarms or resources with no recent traffic.

How do I check from a script whether any alarms are firing?

Combine --state ALARM with --agent. The --state filter limits results to firing alarms, and --agent emits a JSON object with an alarms array instead of interactive output — so an empty array means nothing is firing. This makes it straightforward to gate a deployment in CI on whether a production stage has any active alarms.

How is this different from stacktape metrics?

The metrics command fetches CloudWatch metrics for a deployed resource, with support for metrics like Lambda Invocations, ECS CPUUtilization, RDS DatabaseConnections, and API Gateway 5XXError. The alarms command shows the evaluated state of alarm rules — whether configured thresholds have been breached. Use metrics to investigate trends; use alarms to check whether anything is currently broken.