The container shell command starts an interactive session inside a running container in your deployed stack. The session is established using ECS Exec and an SSM (Systems Manager) connection, giving you direct terminal access to debug, inspect files, or troubleshoot issues in a running container.
Usage
Open a session by specifying the target stage, region, and resource name.
This opens an interactive session inside the container running in the specified resource. The target workload must be a deployed workload with an ECS task definition. Stacktape looks for running ECS tasks before opening the session. When multiple tasks are running, Stacktape prompts you to choose one.
This command does not require a Stacktape configuration file. It connects directly to the deployed stack using the resource name argument (container shell <resource-name>) and the --stage and --region flags. Use optional stack arguments such as --project, --aws-account, or --profile when your local defaults are not enough to identify the target stack or AWS credentials.
Important flags
The two most commonly used optional flags are --command and --container. Both affect which process and which container you connect to.
--command specifies the command that starts the interactive session inside the container. Use it to select a specific shell (like bash). To run a one-shot command and capture its output non-interactively, use container exec instead.
Start a bash session:
--container selects a specific container in multi-container workloads. If the target workload has more than one container definition, specify the container name with --container. Stacktape raises an error and includes the available container names when multiple containers exist and --container is omitted, or when the specified name does not match any container in the workload.
Multiple running instances
When the target resource has multiple running tasks (for example, a scaled-out web service), the CLI prompts you to choose which instance to connect to. Each option shows the task ID and its start time so you can identify the right one.
Arguments reference
stacktape container shell <resource-name>CLI 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.
--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.
--commandstringCommand
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.
-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.
Common errors
- Resource cannot be resolved — Stacktape throws an error when the resource name does not match a deployed workload with an ECS task definition. Check that the resource name matches a deployed workload in the target stage and AWS region.
- Multiple containers without
--containerflag — The target workload has more than one container. The error message lists the available container names. Re-run the command with--containerset to one of those names.
Examples
The following examples show common container shell usage patterns across different workload types and configurations.
Inspect the filesystem of a running web service:
Connect to a specific container in a multi-container workload:
Open a bash session:
Related commands
container exec— run a single command inside a container and return the output (non-interactive). Use this when you need to capture command output programmatically rather than open a live shell.bastion shell— start an interactive session on a bastion host, useful for accessing private VPC resources.logs— fetch and filter logs from deployed resources without opening a shell session.