The bastion shell command starts an interactive shell on a deployed bastion host. The session is established over SSM, so no SSH keys or open inbound ports are required.
Usage
Your stack must contain at least one bastion resource. The --bastion-resource flag is optional — use it when the deployed stack has multiple bastions and you need to choose which one to connect to.
The command does not modify your stack and does not require a Stacktape configuration file.
How it works
When you run bastion shell, Stacktape initializes stack services, resolves the bastion EC2 instance ID from the deployed stack overview, and starts an SSM shell session in the selected region. Your terminal becomes an interactive shell on the bastion host.
The bastion shell command resolves the bastion EC2 instance ID from the deployed stack overview and starts an SSM shell session in the target region. If Stacktape cannot resolve the instance ID, verify that the target stack includes the selected bastion resource.
CLI reference
stacktape bastion shellCLI 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.
--bastion-resourcestringBastion Resource Name
The name of the bastion resource as defined in your Stacktape configuration.
-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.
--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.
Examples
Connect to the only bastion in a stack
When your stack has a single bastion resource, you can omit --bastion-resource.
Connect to a specific bastion by name
When your configuration defines more than one bastion, specify which one to connect to.
Use a specific AWS profile
Troubleshooting
The command requires a deployed bastion resource in the target stack. If Stacktape cannot resolve a bastion resource from the deployed stack, the command fails. Ensure you have deployed a stack that includes at least one bastion before running this command.
When using --bastion-resource, the value must match the name of a bastion resource in your configuration. If the name does not match any bastion in the deployed stack, the command reports an error.
Related commands
bastion tunnel— create a secure tunnel through a bastion to reach a private resource (database, Redis, OpenSearch) from your local machine.query sql— run read-only SQL queries against a deployed database. Supports--bastion-resourceto tunnel through a bastion when the database is VPC-only.query redis— query a deployed Redis cache. Also supports--bastion-resourcefor VPC-only clusters.