Repository files navigation

A CLI tool for navigating AWS ECS clusters interactively.

When running services in ECS, I constantly needed to check:

• What exactly is running where?
• Is my service healthy?
• What parameters or environment variables got applied?
• What do the latest logs show - did the container start as expected?

The AWS ECS web console is confusing to navigate, with multiple clicks through different screens just to get basic information. The AWS CLI is powerful but verbose and requires memorizing complex commands.

lazy-ecs solves this with a simple, interactive CLI that lets you quickly drill down from clusters → services → tasks → containers with just arrow keys. It destroys the AWS CLI in usability for ECS exploration and debugging.

# Add the tapbrew tap vertti/lazy-ecs# Install lazy-ecsbrew install lazy-ecs# Run itlazy-ecs

# Clone and install with uvgit clone https://github.com/vertti/lazy-ecs.gitcd lazy-ecsuv syncuv run lazy-ecs

lazy-ecs supports multiple ways to authenticate with AWS:

lazy-ecs --profile your-profile-name

export AWS_DEFAULT_PROFILE=your-profile-namelazy-ecs

aws-vaultexec Platform-Test.AWSAdministratorAccess -- lazy-ecs

lazy-ecs will automatically use the standard AWS credentials chain:

• Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
• AWS credentials file (~/.aws/credentials)
• IAM instance profile (when running on EC2)

• ✅Container log viewing - Display recent logs with timestamps from CloudWatch
• ✅Container log live tail viewing - Display logs live tail with timestamps from CloudWatch
• ✅Basic container details - Show container name, image, CPU/memory configuration
• ✅Show environment variables & secrets - Display environment variables and secrets configuration (without exposing secret values)
• ✅Show port mappings - Display container port configurations and networking
• ✅Show volume mounts - Display file system mounts and storage configuration
• ⬜Show resource limits vs usage - Display CPU/memory limits and actual consumption
• ⬜Show health check configuration - Display health check settings and current status
• ⬜Connect to running container - Execute shell commands inside running containers (skip - against immutable philosophy)
• ⬜Export container environment - Save environment variables to .env file for local development
• ⬜Copy container command - Get exact docker run command for local debugging

• ✅Task selection with auto-selection - Automatically select single tasks, interactive selection for multiple
• ✅Comprehensive task details - Display task definition, status, containers, creation time
• ✅Task definition version tracking - Show if task is running desired vs outdated version
• ✅Show task events/history - Display task lifecycle events and failure reasons with smart analysis (OOM kills, timeouts, image pull failures)
• ⬜Show task placement details - Display placement constraints and actual host placement
• ⬜Task definition comparison - Compare current vs desired task definition versions
• ⬜Show security groups - Display networking and security configuration
• ⬜Export task definition - Save task definition as JSON/YAML files
• ⬜Stop/Restart single task - Manually stop tasks for debugging (service will auto-restart)
• ⬜Quick task failure reason - Show failure reason inline without navigation

• ✅Service browsing with status - Display services with health indicators (healthy/scaling/over-scaled)
• ✅Service status indicators - Show running/desired/pending counts with visual status
• ✅Force new deployment - Trigger service redeployment directly from CLI (no more AWS console trips!)
• ✅Show service events - Display service-level events and deployment status with chronological sorting and proper categorization
• ⬜Show deployment history - Display service deployment timeline and rollback options
• ⬜Show auto-scaling configuration - Display scaling policies and current metrics
• ⬜Show load balancer health - Display target group health and routing configuration
• ⬜Service update (image tag) - Update service with new image tag
• ⬜Service update (environment) - Update environment variables for service

• ✅Interactive cluster selection - Arrow key navigation through available ECS clusters
• ✅Log group discovery - Automatically find relevant log groups for debugging
• ⬜Multi-cluster support - Compare resources across clusters
• ⬜Bulk operations across clusters - Perform operations on multiple clusters

• ⬜Enhanced log features:
  • ⬜ Search/filter logs by keywords or time range
  • ✅ Follow logs in real-time (tail -f style) - complex UI implementation
  • ⬜ Download logs to file
• ⬜Monitoring integration:
  • ⬜ Show CloudWatch metrics for containers/tasks
  • ⬜ Display resource utilization trends
• ⬜Port forwarding to container - Direct local connection to container ports for debugging
• ⬜Multi-region support - Work with ECS across different AWS regions

Install tools withmise:

mise install

# Install dependenciesuv sync# Install pre-commit hooks (runs ruff formatting/linting on commit)uv run pre-commit install

# Run the CLIuv run lazy-ecs# Run testsuv run pytest# Format and lint code (with type annotation enforcement)uv run ruff formatuv run ruff check --fix# Type checking with pyreflyuv run pyrefly check# Auto-add missing type annotationsuv run pyrefly infer# Run tests with coverageuv run pytest --cov

SeeCLAUDE.md for detailed development guidelines.