- Notifications
You must be signed in to change notification settings - Fork3
A CLI tool for navigating AWS ECS clusters interactively.
License
vertti/lazy-ecs
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
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.
Interactive cluster selection
- Arrow key navigation through ECS clusters
- Why it's great: AWS console requires multiple clicks through menus; AWS CLI requires memorizing cluster ARNs
Service browsing with smart status indicators
- Visual health indicators (✅ healthy,
⚠️ scaling, 🔴 over-scaled) - Running/desired/pending task counts at a glance
- Why it's great: AWS console hides task counts in separate tabs; requires mental math to determine service health
Open in AWS console
- One-key shortcut to open current resource in browser
- Works for clusters, services, and tasks
- Why it's great: When you need the full AWS console, jump there instantly without manual navigation
Container details
- Name, image, CPU/memory configuration
- Environment variables and secrets (without exposing values)
- Port mappings and volume mounts
- Why it's great: AWS console spreads this across multiple tabs; AWS CLI requires complex JSON parsing
Log viewing with live tail
- Display recent logs with timestamps
- Real-time streaming (tail -f style)
- CloudWatch filter patterns (include/exclude)
- Why it's great: AWS console log viewer is slow and clunky; AWS CLI requires memorizing log group names and complex filter syntax
Force new deployment
- Trigger service redeployment directly from CLI
- Why it's great: AWS console requires navigating to service → Update → Force new deployment (3+ clicks)
Service events
- Display deployment events with chronological sorting
- Proper event categorization
- Why it's great: AWS console shows events in reverse chronological order, making it hard to follow deployment progression
Task events/history with smart analysis
- Lifecycle events and failure reasons
- Automatic detection of common failures (OOM kills, timeouts, image pull failures)
- Shows desired vs actual task definition versions (spot outdated tasks immediately)
- Why it's great: AWS console requires clicking into each failed task individually; no smart analysis of failure patterns; no easy way to spot version mismatches
CloudWatch metrics
- CPU/Memory utilization with current, average, and peak values
- Why it's great: AWS console requires switching to CloudWatch tab, selecting metrics, configuring graphs
Log group discovery
- Automatically find relevant log groups for debugging
- Why it's great: AWS console requires knowing the exact log group name; AWS CLI requires listing all log groups and filtering manually
Task definition comparison
- Compare any two task definition revisions side-by-side
- Interactive revision selection from recent history
- Color-coded diff showing images, environment variables, secrets, CPU/memory, ports, commands, entrypoints, and volume mounts
- Why it's great: AWS console has no native comparison tool; developers must download JSON and use external diff tools to answer "what changed between versions?"
# Add the tapbrew tap vertti/lazy-ecs# Install lazy-ecsbrew install lazy-ecs# Run itlazy-ecs
Install in an isolated environment using your preferred tool manager:
# Using pipxpipx install lazy-ecs# Using uvuv tool install lazy-ecs# Using misemise use pipx:lazy-ecs# Run itlazy-ecs
Run lazy-ecs using Docker without installing Python:
# With aws-vault (temporary credentials)aws-vaultexec your-profile -- docker run -it --rm \ -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN -e AWS_REGION \ vertti/lazy-ecs# With IAM credentials (long-lived)docker run -it --rm \ -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_REGION \ vertti/lazy-ecs# With AWS credentials filedocker run -it --rm -v~/.aws:/home/lazyecs/.aws:ro vertti/lazy-ecs# With specific profiledocker run -it --rm -v~/.aws:/home/lazyecs/.aws:ro -e AWS_PROFILE=your-profile vertti/lazy-ecs
Pro tip: Create an alias for easier usage:
# Add to your ~/.bashrc or ~/.zshrcalias lazy-ecs-docker='docker run -it --rm -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN -e AWS_REGION vertti/lazy-ecs'# Then use with aws-vaultaws-vaultexec your-profile -- lazy-ecs-docker
# 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)
Features listed in priority order:
- Resource usage vs limits - Show allocated vs actual CPU/memory with right-sizing recommendations
- Export task definition - Save task definitions as JSON/YAML files
- Task placement details - Display placement constraints and actual host placement
- Health check configuration - Display health check settings and current status
- Download logs to file - Export CloudWatch logs for offline analysis
- Sparkline visualization - Unicode trend indicators for metrics
- Service deployment history - Timeline of deployments with rollback options
- Security groups - Display networking and security configuration
- Auto-scaling configuration - Display scaling policies and current metrics
- Load balancer health - Display target group health and routing
- Quick task failure reason - Show failure reason inline without navigation
- Export container environment - Save environment variables to .env file
- Multi-region support - Work with ECS across AWS regions
- Service update (image tag) - Deploy new image version from CLI
- Service update (environment) - Update environment variables
- Multi-cluster support - Compare resources across clusters
- Port forwarding - Direct local connection to container ports
- Stop/restart single task - Force restart individual tasks
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.
About
A CLI tool for navigating AWS ECS clusters interactively.
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Contributors3
Uh oh!
There was an error while loading.Please reload this page.