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.
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:
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)requiredstringCommand
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)requiredstringResource Name
The name of the resource as defined in your Stacktape configuration.
-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.
-c, --configstringConfig 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.
--containerstringContainer Name
The name of the container as defined in your container compute resource configuration.
--cwdstringCurrent 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, --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.
--task-arnstringTask ARN
Specific ECS task ARN to connect to.
Examples
Inspect a configuration file
Check environment variables
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.
Target a specific container in a multi-container workload
For multi-container workloads with multiple containers, specify which container to execute in.
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.
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.
Related commands
| Command | Purpose |
|---|---|
container shell | Start an interactive shell session inside a running container |
logs | Fetch and filter logs from a deployed resource |
metrics | View CloudWatch metrics for a deployed resource |
bastion tunnel | Create 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.