Debug Commands Reference

Stacktape provides a suite of CLI commands for inspecting deployed stacks without leaving your terminal. This page documents logs and metrics in depth and covers the essentials of each remaining command with links to dedicated CLI reference pages. The container exec command runs a one-shot command inside a running container and returns its output, while container shell and bastion shell open interactive shell sessions — treat all three with appropriate care in production stages, since they let you run arbitrary commands against live infrastructure.

Command overview

CommandPurpose
logsFetch CloudWatch log events
metricsFetch CloudWatch metric data
alarm listInspect CloudWatch alarms
query sqlQuery SQL databases
query dynamodbQuery DynamoDB tables
query redisInspect Redis caches
query opensearchQuery OpenSearch domains
aws callRun AWS SDK calls
container execExecute a command in a container
container shellInteractive container shell
bastion tunnelPort-forwarding through a bastion
bastion shellSSM shell on a bastion instance
This page covers logs and metrics in depth. For the other commands, use the linked CLI reference pages for their flags, operations, and requirements.

Stack targeting

Debug commands target a deployed stack through the usual Stacktape stack-selection flags (--project, --stage, --region). logs and metrics require --resource-name to pick a specific resource; other resource-specific commands document their own required targeting flags on their CLI reference pages. The exact targeting flags supported by each command — and any defaults applied when a flag is omitted — are documented on each command's CLI reference page.

Viewing logs

The stacktape logs command fetches CloudWatch log events for a deployed resource. It requires --resource-name, resolves that resource's log group through Stacktape's log-group helper, and retrieves events from CloudWatch Logs.

Basic usage

Fetch the last hour of logs for a resource:

stacktape logs api --project myProject --stage prod --region eu-west-1

Time range

Use --since with relative notation (1h, 30m, 1d, 5s) or an ISO timestamp. The default lookback window is 1 hour from the current time.

Fetch the last 30 minutes:

stacktape logs api --since 30m

For standard log fetching, Stacktape passes startTime to CloudWatch Logs. --until is used as the reference point when parsing relative --since; Logs Insights queries pass both startTime and endTime.

Filtering

Use --filter to pass a CloudWatch Logs filter pattern.

Filter for lines containing "ERROR":

stacktape logs api --filter "ERROR"

Filter JSON structured logs by a field:

stacktape logs api --filter '{ $.level = "error" }'

CloudWatch Logs Insights queries

Use --query to run a full CloudWatch Logs Insights query against the resource's log group. Logs Insights supports aggregations, sorting, field extraction, and explicit time bounds via --since and --until.

stacktape logs api --query "fields @timestamp, @message | filter @message like /ERROR/ | sort @timestamp desc | limit 20"

Fetch Logs Insights results between two absolute timestamps:

stacktape logs api --query "fields @timestamp, @message | sort @timestamp desc" --since "2025-01-15T10:00:00Z" --until "2025-01-15T11:00:00Z"

Output format

  • --raw — outputs raw JSON instead of formatted terminal output
  • --limit — maximum number of events to return (default: 100)
  • --container — for multi-container workloads, specify which container's logs to fetch

Without --raw, Stacktape passes the limited events to the formatted log printer.

Agent mode

When invoked by an AI coding assistant (detected automatically), logs returns structured JSON. Standard log fetching returns { logGroup, events }:

{
  "logGroup": "/aws/lambda/myStack-api",
  "events": [
    {
      "timestamp": "2025-01-15T10:30:00.000Z",
      "message": "Processing request",
      "logStream": "2025/01/15/[$LATEST]abc123"
    }
  ]
}

Logs Insights queries (when using --query) return { logGroup, query, results } instead.

This makes debug commands work as data sources for coding agents through the Stacktape MCP server.

Viewing metrics

The stacktape metrics command fetches CloudWatch metric data for a specific resource and renders a chart in your terminal. It supports four resource types, each with a fixed set of available metrics.

Supported resource types and metrics

Resource typeCloudWatch namespaceAvailable metrics
function (Lambda)AWS/LambdaInvocations, Errors, Duration, Throttles, ConcurrentExecutions
multi-container-workloadAWS/ECSCPUUtilization, MemoryUtilization
relational-databaseAWS/RDSCPUUtilization, DatabaseConnections, FreeStorageSpace, ReadLatency, WriteLatency
http-api-gatewayAWS/ApiGatewayCount, 4XXError, 5XXError, Latency, IntegrationLatency

The metrics command checks the resource's type from the deployed stack. If the type isn't in this table, the command returns an error listing the supported types.

Basic usage

View Lambda invocations over the last hour:

stacktape metrics api Invocations

Customizing the query

  • --period — aggregation interval in seconds (default: 300, i.e. 5 minutes)
  • --stat — CloudWatch aggregation statistic (default: Average). Standard CloudWatch statistics include Average, Sum, Minimum, Maximum, and SampleCount.
  • --since — supports relative time (1h, 6h, 1d) or ISO timestamp (default: 1 hour ago)
  • --until — end of the time window (default: now)

View database CPU over the last 24 hours with 1-hour granularity:

stacktape metrics mainDb CPUUtilization --since 1d --period 3600

Terminal output

In interactive mode, Stacktape renders the returned datapoints as a formatted metrics chart. In agent mode, the command returns structured JSON with timestamps and values for programmatic consumption.

Viewing alarms

The stacktape alarm list command inspects CloudWatch alarm state for a deployed stack. See the CLI reference for the full flag list and behavior.

Querying SQL databases

The stacktape query sql command runs SQL queries against a deployed relational database from the CLI. See the CLI reference for supported query behavior and flags.

Querying DynamoDB

The stacktape query dynamodb command inspects DynamoDB table contents and schema from the CLI. See the CLI reference for the full list of operations and flags.

Querying Redis

The stacktape query redis command inspects keys and server info on a deployed Redis cache. See the CLI reference for the full list of operations and flags.

Querying OpenSearch

The stacktape query opensearch command queries deployed OpenSearch domains from the CLI. See the CLI reference for the full list of operations and flags.

Running AWS SDK commands

The stacktape aws call command runs AWS SDK v3 calls against your deployed stack as an escape hatch for resources without a dedicated debug command. See the CLI reference for the full flag list and restrictions.

Executing commands in containers

The stacktape container exec command runs a one-shot command inside a running container and returns the output. See the CLI reference for the full flag list.

container exec and container shell execute arbitrary commands inside live containers. These are NOT read-only operations — use caution in production stages.

Interactive container shell

The stacktape container shell command opens an interactive shell session inside a running container. See the CLI reference for the full flag list.

Bastion tunneling

The stacktape bastion tunnel command opens a local port-forwarding tunnel through a bastion host to reach VPC-only resources. See the CLI reference for the full flag list and target behavior.

Bastion shell session

The stacktape bastion shell command opens an interactive SSM shell session on a bastion host EC2 instance. See the CLI reference for the full flag list.

Credentials and permissions

logs loads your configured AWS credentials to call CloudWatch Logs APIs. metrics initializes stack services for a deployed stack and queries CloudWatch metrics. Other debug and session commands have their own credential and IAM requirements documented on their dedicated CLI reference pages.

Debug Commands Reference FAQ

How do I view real-time logs as they arrive?

In a terminal, stacktape logs shows recent events and follows new lines by default. Use --follow=false for a snapshot. Piped, redirected and agent runs take snapshots unless --follow is requested. For the development workflow, see dev mode.

Can I use debug commands with dev mode stacks?

logs and metrics require a deployed stack as their target. If you are running stacktape dev, these commands can target the deployed AWS stack that dev mode created — specify the same --project, --stage, and --region. Other debug commands have their own deployment requirements documented on their CLI reference pages.

How do I debug a VPC-only database without a bastion?

Options for debugging private resources depend on what you've deployed. The simplest path is to add a bastion host to your stack and use bastion tunnel to forward a local port to the database. If you use container shell access for private-resource debugging, see the container shell and container exec CLI reference pages for requirements.

What's the difference between container exec and container shell?

container exec runs a single command and returns its output — it's non-interactive and suitable for scripting or AI agent use. container shell opens a persistent interactive shell. Use container shell for exploratory debugging; use container exec for automated checks.

How do I know which metrics are available for my resource?

The metrics command supports a fixed set of metrics per resource type (listed in the metrics table above). If the metric name doesn't match the resource type's allowed list, the command returns an error with the valid options. For metrics not in that list, use aws call with the CloudWatch GetMetricData or ListMetrics commands.

How much do debug commands cost?

Debug commands themselves are CLI operations with no direct charge. The underlying AWS API calls (such as CloudWatch GetLogEvents and GetMetricData) may incur standard AWS charges according to your account and region. CloudWatch Logs Insights queries (--query flag on logs) are charged by AWS based on the amount of data scanned.

Can I pipe debug command output to other tools?

Pass --raw to logs to get structured JSON output instead of formatted terminal text — this is suitable for piping to jq or saving to a file. Both logs and metrics return structured JSON in agent mode. In interactive mode, output is formatted for terminal viewing and isn't designed for piping.