cshell

A small CLI for managing AWS CloudShell environments and opening an interactive session from your terminal — no browser required.

It signs the (unofficial) CloudShell API with SigV4 using your AWS credentials and hands the session off to the AWS session-manager-plugin.

The CloudShell environment management API is unofficial and undocumented; this tool relies on observed behavior and may break if AWS changes it.

Install

Homebrew (macOS/Linux):

brew install avoidik/cshell/cshell

Or download a prebuilt binary for your platform (Linux/macOS, x86-64/arm64) from the Releases page, e.g.:

tar -xzf cshell_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz
sudo mv cshell /usr/local/bin/

Or with Go:

go install github.com/avoidik/cshell@latest   # or: go build -o cshell .

Releasing

Releases are built by GoReleaser on tag push (CI builds Linux/macOS × amd64/arm64 archives + checksums):

git tag v0.1.0 && git push origin v0.1.0

Requirements

• The AWS session-manager-plugin on your PATH (used to open the interactive session).
• An AWS named profile that resolves to temporary credentials (a session token is required). AWS IAM Identity Center (SSO) profiles work great — run aws sso login --profile <name> first. The profile needs the AWSCloudShellFullAccess permissions.

Credentials and region are resolved with the standard AWS SDK chain, so the region comes from your profile automatically (override with -region).

Usage

cshell <command> [flags]

Commands:
  connect   Connect to a CloudShell environment (creating one if needed)
  list      List CloudShell environments and their status
  status    Show the status of an environment
  create    Create a CloudShell environment
  delete    Delete a CloudShell environment
  vpcs      List VPCs (or subnets + security groups with -vpc-id)

Common flags:
  -profile <name>   AWS named profile (default: $AWS_PROFILE)
  -region <region>  AWS region (default: the profile's region)
  -id <id>          Target environment id (connect/status/delete)

VPC flags (connect/create):
  -vpc-id, -subnet-id, -sg-id   Attach the environment to a VPC

Examples

# Connect (discovers/creates the environment, waits for it, opens a shell)
cshell connect

# Use a specific profile/region
cshell connect -profile dev -region eu-west-1

# List environments
cshell list

# Connect to a specific environment when more than one exists
cshell connect -id abcdefgh-aaaa-bbbb-cccc-dddddddddddd

# Discover VPC resources, then attach a VPC
cshell vpcs
cshell vpcs -vpc-id vpc-xxxxxxxx
cshell connect -vpc-id vpc-xxxxxxxx -subnet-id subnet-xxxxxxxx -sg-id sg-xxxxxxxx

# Delete without the confirmation prompt
cshell delete -id abcdefgh-aaaa-bbbb-cccc-dddddddddddd -yes

Notes

• One environment per account/region. connect reuses the existing environment (resuming it if suspended), and only creates one when none exists.

• VPC environments can only reach what the VPC allows — AWS API calls from the shell will time out unless the subnet has internet egress (NAT/Internet gateway) or interface VPC endpoints. Omit the VPC flags for default networking.

• Credentials inside the shell: an environment created through the API does not carry credentials of its own. Pass -inject to connect to push your (temporary) credentials into the shell as environment variables:

  cshell connect -inject

  Injection is opt-in (it writes credentials into the shell environment) and is skipped for VPC-attached environments. Without it, export credentials yourself in the shell, or use an environment created via the AWS Console (which already has working credentials).