ecs-shell 1.0.0

Interactive shell for AWS ECS tasks with service and task selection.

ecs-shell

ecs-shell is yet another interactive CLI tool for connecting to AWS ECS (Elastic Container Service) tasks. It provides a user-friendly interface to browse services, select tasks, and establish shell sessions - all without having to remember complex AWS CLI commands or task IDs.

I have created this as an utility for me in the past, and only later found that there are plenty of others out there. I think the CLI UX with this one is better, so I decided to publish it anyways.

https://github.com/user-attachments/assets/065ad13e-38fc-4e71-a9bc-d57973d347f7

✨ Features

• 🎯 Interactive Selection: Browse and select ECS services and tasks using arrow keys
• 🎨 Rich UI: Beautiful terminal interface with color-coded output
• ⚡ Fast Navigation: Quickly filter through services and tasks
• 📊 Task Details: View task creation time, CPU/Memory allocation, and container information
• 🔄 Session Management: Seamless shell session establishment with AWS ECS Exec
• 🔐 Profile Support: Use any AWS CLI profile for multi-account workflows

📋 Requirements

Before using ecs-shell, ensure you have the following installed and configured:

1. AWS CLI

The AWS CLI must be installed and authenticated with appropriate permissions.

# Install AWS CLI (macOS)
brew install awscli

# Configure your AWS credentials
aws configure

Required AWS Permissions:

• ecs:ListServices
• ecs:ListTasks
• ecs:DescribeTasks
• ecs:ExecuteCommand

2. Session Manager Plugin

The Session Manager plugin is required for establishing interactive sessions with ECS tasks.

# Install Session Manager plugin (macOS)
brew install --cask session-manager-plugin

# Verify installation
session-manager-plugin --version

For other operating systems, see the AWS Session Manager Plugin installation guide.

3. Python

Python 3.10 or higher is required.

# Check your Python version
python3 --version

4. ECS Task Configuration

Your ECS tasks must have ECS Exec enabled. This is configured in your task definition:

{
  "enableExecuteCommand": true
}

🚀 Installation

Using pipx (Recommended)

pipx installs CLI tools in isolated environments, avoiding conflicts:

# Install pipx if you haven't already
brew install pipx
pipx ensurepath

# Install ecs-shell
pipx install ecs-shell

Using pip

# Install globally
pip install ecs-shell

# Or in a virtual environment
python3 -m venv venv
source venv/bin/activate
pip install ecs-shell

Upgrade

# With pipx
pipx upgrade ecs-shell

# With pip
pip install --upgrade ecs-shell

📖 Usage

ecs-shell <profile> <cluster>

Arguments:

• profile: AWS CLI profile name (from ~/.aws/credentials)
• cluster: ECS cluster name

Examples

# Connect to staging cluster using 'production' profile
ecs-shell production my-cluster-staging

# Connect to development cluster
ecs-shell dev-profile dev-cluster

# Use default profile
ecs-shell default my-cluster

🛠️ Development

Setup

# Clone the repo
# Create and activate virtual environment
make setup-venv
source venv/bin/activate

# Install dependencies
make install-deps

# Install ecs-shell in development mode
make local-install

Commands

make lint           # Run linting checks
make format         # Auto-format code
make local-install  # Install package locally (in active environment)

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.