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
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.
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:
Show only healthy alarms:
You can combine both filters to check whether a specific resource has any firing alarms:
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.
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, --stagerequiredstringStage
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-accountstringAWS 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, --helpstringShow 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, --profilestringAWS 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.
--projectstringProject 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.
--quietbooleanQuiet
Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.
--resource-namestringResource Name
The name of the resource as defined in your Stacktape configuration.
--statestringAlarm State Filter
Filter alarms by state: OK, ALARM, or INSUFFICIENT_DATA.
Related commands
stacktape logs— fetch and search logs from a deployed resource.stacktape metrics— fetch CloudWatch metrics for a deployed resource.stacktape error list— list detected runtime issues (errors) across your deployed functions and containers.
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.