ecsx

Your ECS clusters, one keystroke away.

Installation • Usage • Commands • Keybindings

---

ecsx is a terminal UI for Amazon ECS. Browse clusters, services, and tasks in a split-pane interface. Tail logs, scale services, exec into containers, and open SSM sessions — without leaving your terminal.

✨ Highlights

• 🗂 Browse clusters → services → tasks with fuzzy filtering
• 📊 Metrics — CPU and memory sparklines per service
• 📜 Logs — real-time CloudWatch log tailing with filter patterns
• 📝 Editor — open buffered logs in $EDITOR for search and analysis
• ⚖️ Scale — update desired count on the fly
• 🔄 Deploy — force new deployment to restart services
• 🛑 Stop — stop individual tasks
• 🔃 Auto-refresh — background refresh every 30s, toggle with a
• 🔑 Env vars — inspect container environment, copy to clipboard
• 🐚 Exec — shell into running containers via ECS ExecuteCommand
• 🔌 SSM — connect to EC2 container instances
• ⌨️ Completions — bash, zsh, fish, powershell

Prerequisites

• AWS credentials configured (via CLI, env vars, or IAM role)
• session-manager-plugin — required for exec and ssm commands

Installation

Go:

go install github.com/ron/ecsx/cmd/ecsx@latest

From source:

git clone https://github.com/ron/ecsx.git
cd ecsx
make install

Usage

ecsx                          # launch TUI, browse all clusters
ecsx -c my-cluster            # jump straight to a cluster
ecsx -p prod -r eu-west-1     # specify AWS profile and region

Commands

ecsx logs — tail CloudWatch logs

ecsx logs -c my-cluster -s my-service
ecsx logs -c my-cluster -s my-service -f "ERROR"         # filter pattern
ecsx logs -c my-cluster -s my-service -G "ERR|WARN"      # client-side regex grep
ecsx logs -c my-cluster -s my-service -b 2h              # last 2 hours
ecsx logs -c my-cluster -s my-service --no-follow        # dump and exit

-f is a server-side CloudWatch filter pattern — it reduces the data sent from AWS. -G is a client-side regex applied after receiving the logs, useful for patterns CloudWatch filters can't express:

# Only show ERROR and WARN lines
ecsx logs -c my-cluster -s my-service -G "ERROR|WARN"

# Match slow requests (4+ digit durations)
ecsx logs -c my-cluster -s my-service -G "duration=[0-9]{4,}ms"

# Filter by specific HTTP status codes (5xx errors)
ecsx logs -c my-cluster -s my-service -G "HTTP/[0-9.]+ 5[0-9]{2}"

# Match a specific user or request ID
ecsx logs -c my-cluster -s my-service -G "user=(alice|bob)"

# Case-insensitive match
ecsx logs -c my-cluster -s my-service -G "(?i)timeout|deadline"

# Combine server-side filter with client-side grep
ecsx logs -c my-cluster -s my-service -f "ERROR" -G "database|connection"

ecsx exec — shell into a container

ecsx exec -c my-cluster -s my-service                    # /bin/sh into first task
ecsx exec -c my-cluster -s my-service --cmd "ls -la"     # run a command
ecsx exec -c my-cluster -t <task-id> -u my-container     # target specific task + container

Requires session-manager-plugin and enableExecuteCommand enabled on the ECS service.

ecsx ssm — connect to EC2 instances

ecsx ssm -c my-cluster -s my-service     # resolve instance from service tasks
ecsx ssm -c my-cluster -i i-0abc123      # connect directly

ecsx task — describe a task

ecsx task -c my-cluster -s my-service                    # describe first task in service
ecsx task -c my-cluster -s my-service -t <task-id>       # describe specific task

ecsx container-env — list container environment variables

ecsx container-env -c my-cluster -s my-service                          # table format
ecsx container-env -c my-cluster -s my-service --format export          # export KEY="value"
ecsx container-env -c my-cluster -s my-service --format docker          # -e KEY=value
ecsx container-env -c my-cluster -s my-service --container my-container # specific container

ecsx completion — shell completions

ecsx completion bash | sudo tee /etc/bash_completion.d/ecsx
ecsx completion zsh > ~/.zfunc/_ecsx
ecsx completion fish > ~/.config/fish/completions/ecsx.fish

Keybindings

Key	Action
enter	Drill into selected item
esc	Go back
/	Filter list or logs
f	Cycle log level (in logs)
g	Regex grep filter (in logs)
l	Tail logs
e	Open logs in $EDITOR / toggle env vars
y	Copy env vars to clipboard
s	Scale service
x	Deploy / stop task / SSM session
r	Refresh
a	Toggle auto-refresh
+ -	Toggle zoom
?	Help
q	Quit

Global Flags

Flag	Short	Description
--profile	-p	AWS profile
--region	-r	AWS region
--cluster	-c	ECS cluster (skip selection)

IAM Permissions

By default, ecsx is non-destructive — browsing clusters, services, tasks, logs, and metrics requires only read-only permissions. Write actions (scale, deploy, stop, exec, ssm) are opt-in and triggered explicitly by the user.

Read-only (browsing, logs, metrics)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:ListClusters",
        "ecs:DescribeClusters",
        "ecs:ListServices",
        "ecs:DescribeServices",
        "ecs:ListTasks",
        "ecs:DescribeTasks",
        "ecs:ListContainerInstances",
        "ecs:DescribeContainerInstances",
        "ecs:DescribeTaskDefinition",
        "cloudwatch:GetMetricStatistics",
        "logs:DescribeLogGroups",
        "logs:StartLiveTail",
        "logs:FilterLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

Write actions (scale, deploy, stop)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:UpdateService",
        "ecs:StopTask"
      ],
      "Resource": "*"
    }
  ]
}

ECS Exec and SSM sessions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:ExecuteCommand"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ssm:StartSession"
      ],
      "Resource": "*"
    }
  ]
}

Inspiration

Built on the shoulders of these great tools:

• ecsq — friendly ECS CLI for querying clusters, services, and tasks
• cw — CloudWatch Logs tail from the terminal
• gossm — interactive SSM session manager

License

MIT