container exec

The container exec command runs a one-off command inside a deployed container workload and returns the output as structured JSON. Use it to inspect files, check environment variables, run health checks, or execute diagnostic commands against web services, private services, worker services, or multi-container workloads without opening an interactive shell.

When to use

Use container exec when you need a quick, non-interactive answer from a running container — checking a config file, listing directory contents, printing environment variables, or verifying a process is running. The structured JSON output makes it suitable for scripting and automation.

For an interactive shell session (debugging, exploring, running multiple commands), use container shell instead. For viewing application logs, use stacktape logs.

Usage

The command takes the resource name and the command to run as positional arguments (container exec <resource-name> <command>) and requires --stage and --region.

stacktape container exec myService "ls -la /app" --stage prod --region eu-west-1

The container exec command does not require a Stacktape configuration file. It resolves the target stack from the --stage, --region, and --project (or --aws-account) flags. You can run it from any directory, even outside a configured project. If you have not configured a default project with defaults set, include --project to identify the stack.

The command prints a JSON object with the execution result:

{
  "resourceName": "myService",
  "containerName": "myService",
  "taskArn": "arn:aws:ecs:eu-west-1:123456789:task/cluster/abc123",
  "command": "ls -la /app",
  "output": "total 24\ndrwxr-xr-x 1 root root 4096 ...",
  "exitCode": 0
}

The output field contains the command output returned by Stacktape's ECS Exec helper. The exitCode field reflects the command's exit code — 0 for success, non-zero for failure.

Important flags

<command> (required, second positional argument) — The shell command to execute inside the container. Wrap multi-word commands in quotes.

<resource-name> (required, first positional argument) — The name of the container workload resource as defined in your Stacktape configuration.

--container — Specifies which container to run the command in. When the task definition has one container, Stacktape uses that container when --container is omitted. For resources with multiple containers (e.g., a multi-container workload with sidecars), omitting this flag or specifying a name not in the task definition causes the command to fail with an error listing the available container names.

--task-arn — Target a specific ECS task when multiple instances are running (e.g., a scaled-out service). Accepts either a full ARN or just the task ID suffix. Defaults to the first running task if omitted.

--agent — A global CLI flag that optimizes output for programmatic and AI-agent consumption. Switches output to strict JSONL format and disables the interactive terminal UI.

Command reference

stacktape container exec <resource-name> <command>CLI options
--command (positional 2)requiredstring

Command

This argument has different meanings depending on the command:

  • With stacktape help, it specifies a command to show detailed help for.
  • With stacktape container shell, it specifies a command to run inside the container to start the interactive session.
-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.

--resource-name (positional 1)requiredstring

Resource Name

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

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

-c, --configstring

Config File Path

The path to your Stacktape configuration file, relative to the current working directory. Without it, Stacktape uses the one stacktape.ts, stacktape.yml, stacktape.yaml or stacktape.js in the working directory. When there are several, the command stops and asks you to choose one with this option.

--containerstring

Container Name

The name of the container as defined in your container compute resource configuration.

--cwdstring

Current Working Directory

The working directory for the operation. All file paths in your configuration will be resolved relative to this directory. By default, this is the directory containing the configuration file.

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

--task-arnstring

Task ARN

Specific ECS task ARN to connect to.

Examples

Inspect a configuration file

stacktape container exec apiService "cat /app/config.json" --stage prod --region eu-west-1

Check environment variables

stacktape container exec apiService "env" --stage prod --region eu-west-1

Target a specific task in a scaled-out service

When a service has multiple running tasks (scaled beyond one instance), use --task-arn to target a specific one. You can use the short task ID instead of the full ARN.

stacktape container exec apiService "ps aux" --stage prod --region eu-west-1 --task-arn abc123def

Target a specific container in a multi-container workload

For multi-container workloads with multiple containers, specify which container to execute in.

stacktape container exec myWorkload "cat /var/log/sidecar.log" --stage prod --region eu-west-1 --container sidecar

Use in scripts or CI pipelines

The JSON output can be parsed with jq or similar tools. Use --agent for machine-readable output in scripts.

stacktape container exec apiService "cat /app/version.txt" --stage prod --region eu-west-1 --agent | jq -r '.output'

Common errors

Resource is not a container workload

The resource name you specified doesn't match any deployed ECS-based container workload. Verify the resource name matches your Stacktape configuration and that the stage has been deployed. Only web services, private services, worker services, and multi-container workloads are supported.

Multiple containers require the --container flag

The target resource has multiple containers in its task definition. The error lists the available container names. Re-run the command with --container <name> to select one.

No running tasks found

The ECS service has no running tasks. Wait for tasks to start or check the ECS service status. This can happen if the service has not finished deploying, or if the resource is a dev stack without running containers.

Task not found

The --task-arn you specified doesn't match any running task. The error lists the available task IDs you can use instead.

CommandPurpose
container shellStart an interactive shell session inside a running container
logsFetch and filter logs from a deployed resource
metricsView CloudWatch metrics for a deployed resource
bastion tunnelCreate a secure tunnel to a VPC resource through a bastion host

container exec FAQ

What is the difference between container exec and container shell?

container exec runs a single command non-interactively and returns the output as structured JSON — ideal for scripting, CI pipelines, and AI agent workflows. container shell opens an interactive shell session where you can type multiple commands in real time. Use container exec when you know exactly what you need; use container shell when you need to explore or debug interactively.

Which resource types work with container exec?

Any ECS-based container workload works: web services, private services, worker services, and multi-container workloads. Lambda functions and other non-container resources are not supported — the command validates the target is an ECS-based resource before proceeding.

Does container exec modify the running container?

The command can execute any shell command, including ones that write files or change state inside the container. However, ECS tasks run on ephemeral compute (AWS Fargate or EC2 instances managed by ECS). Any filesystem changes are lost when the task restarts or is replaced during a deployment. Do not rely on container exec for persistent configuration changes.

How does container exec connect to the container?

Stacktape runs the command using AWS ECS Exec through the SSM session-manager-plugin. In AWS, ECS Exec uses Systems Manager Session Manager rather than SSH — no SSH keys or open ports are required.