ecsctl

A CLI tool for managing Amazon ECS resources, inspired by eksctl.

📖 Read the full documentation

---

Installation

1. Using the installation script (Recommended)

macOS / Linux:

curl -fsSL https://roslaan001.github.io/ecsctl/install.sh | sh

Windows (PowerShell):

irm https://roslaan001.github.io/ecsctl/install.ps1 | iex

2. Using go install

go install github.com/roslaan001/ecsctl@latest

3. From source

git clone https://github.com/Roslaan001/ecsctl.git
cd ecsctl
make install

---

Documentation

The full documentation is built with MkDocs and hosted on GitHub Pages. Pull requests build the site, and pushes to main or master publish it to the gh-pages branch through the docs workflow. Installers download release archives directly from GitHub Releases.

To preview the documentation locally, run:

make docs-serve

This will automatically create a local Python virtual environment, install the mkdocs-material theme, and start a live-reloading server at http://127.0.0.1:8000.

---

• Go 1.26+
• AWS credentials configured (~/.aws/credentials, environment variables, or IAM role)
• Session Manager plugin (required for ecsctl exec)

Authentication

ecsctl uses the standard AWS credential chain — environment variables, ~/.aws/credentials, or IAM roles. Use --region and --profile flags to override per command.

---

Declarative Resource Management

You can manage resources declaratively using YAML configurations.

1. Apply (Create or Update)

The apply command creates resources if they are absent or reconciles them if there is a configuration drift.

# Preview changes without applying
ecsctl apply -f cluster.yaml --dry-run

# Apply configuration and wait for stability
ecsctl apply -f service.yaml --wait

cluster.yaml

name: my-cluster
region: us-east-1
capacityProviders:
  - FARGATE
  - FARGATE_SPOT
tags:
  env: production
  team: platform

service.yaml

name: my-service
cluster: my-cluster
taskDefinition: my-task:3
launchType: FARGATE
desiredCount: 2
network:
  subnets:
    - subnet-abc123
  securityGroups:
    - sg-abc123
  assignPublicIp: ENABLED
tags:
  env: production

2. Create

Explicitly create clusters or services using config files or inline flags:

# Create from configuration files
ecsctl create cluster -f cluster.yaml
ecsctl create service -f service.yaml

# Create directly using inline flags
ecsctl create cluster --name my-cluster --region us-east-1
ecsctl create cluster --name my-ec2-cluster --region us-east-1 --ec2
ecsctl create service --name my-service --cluster my-cluster --task-definition my-task:3

New clusters attach the FARGATE capacity provider and use it as the default capacity-provider strategy. Add --ec2 to create an EC2-backed cluster using the region's default VPC, an ECS-optimized Amazon Linux 2023 image, and a t3.small instance by default. ECS creates one instance initially and manages the Auto Scaling group capacity; use --ec2-instance-type and --ec2-count to change the defaults. EC2 instances incur charges while running. Services and one-off tasks use the cluster's default capacity-provider strategy unless you select a launch type explicitly.

ECS service YAML can also configure capacity-provider strategies, deployment controllers and safety settings, load balancers, Service Connect, placement, ECS Exec, tags, and Application Auto Scaling. See the declarative configuration guide.

ECS Express Mode

Create an Express Mode service, which lets ECS provision and manage its ingress, load balancer, scaling, logging, and alarms:

ecsctl express create -f express.yaml --wait
ecsctl express describe --service-arn "$SERVICE_ARN"

See the Express Mode guide for the role requirements and YAML fields.

Task definitions and one-off tasks

Register a task definition JSON file and run or stop standalone ECS tasks. Unless you pass --launch-type, ECS uses the cluster's default capacity-provider strategy:

ecsctl register task-definition -f task-definition.json
ecsctl run-task --cluster my-cluster --task-definition batch:1 --subnets subnet-a --security-groups sg-a
ecsctl stop-task --cluster my-cluster --task <task-id-or-arn>

See the task guide for details.

3. Delete

Delete active clusters or services:

# Delete a service
ecsctl delete service my-service --cluster my-cluster

# Delete a cluster
ecsctl delete cluster my-cluster

---

Imperative Commands & Operations

Deploy

Update an ECS service with a new container image:

# Deploy to the default container
ecsctl deploy my-service --cluster my-cluster --image nginx:1.25

# Deploy to a specific container
ecsctl deploy my-service --cluster my-cluster --image nginx:1.25 --container web

Scale

Scale the desired task count of an ECS service:

ecsctl scale my-service --cluster my-cluster --desired 3

Logs

Stream or retrieve logs from a service's tasks:

# Fetch recent logs
ecsctl logs my-service --cluster my-cluster

# Tail logs with custom line count
ecsctl logs my-service --cluster my-cluster --tail 100

# Stream logs in real-time
ecsctl logs my-service --cluster my-cluster --follow

Exec

Open an interactive shell or run a command inside a running service task container (requires ECS Exec enablement):

# Open interactive shell in default container
ecsctl exec my-service --cluster my-cluster

# Run in a specific container
ecsctl exec my-service --cluster my-cluster --container web

# Run a custom command
ecsctl exec my-service --cluster my-cluster --command "/bin/sh"

---

Inspection & Querying

List

List resources locally from remote state, or directly from live AWS if no state is configured:

# List all ECS clusters
ecsctl list clusters

# List all services in a cluster
ecsctl list services --cluster my-cluster

# List running tasks in a cluster or service
ecsctl list tasks --cluster my-cluster
ecsctl list tasks --cluster my-cluster --service my-service
ecsctl list task-definitions

# Filter, sort, limit, or emit machine-readable output
ecsctl list tasks --cluster my-cluster --desired-status STOPPED --sort startedAt --limit 20
ecsctl list task-definitions --family api --output json

Describe

Retrieve detailed configuration and status information for a specific resource:

# Describe cluster configuration and stats
ecsctl describe cluster my-cluster

# Describe service configuration, deployment, and task status
ecsctl describe service my-service --cluster my-cluster

---

Remote State Management

ecsctl supports storing resource tracking configurations remotely in an S3 bucket. This acts as a shared state file and context manager similar to Terraform state.

1. Initialize State Context

Creates an S3 bucket (or checks existence) in a given region, enables S3 versioning, and saves context details under ~/.ecsctl/config.yaml.

ecsctl state init --context staging --bucket my-ecsctl-staging-state --region eu-west-1
ecsctl state init --context prod --bucket my-ecsctl-prod-state --region us-east-1 --profile prod-profile

2. Switch Contexts

# List configured contexts (* indicates current context)
ecsctl state list-contexts

# Switch the current active context
ecsctl state use-context staging

3. Import Existing Resources

Import your pre-existing AWS ECS resources into ecsctl state control:

# Import an existing cluster
ecsctl state import cluster my-existing-cluster --region us-east-1

# Import an existing service
ecsctl state import service my-existing-service --cluster my-existing-cluster --region us-east-1

4. Show Remote State

Print the S3 path and all tracked clusters and services inside the current state context:

ecsctl state show

5. Check for Drift

Compare saved configurations in the active state context with live ECS resources without changing them:

ecsctl state drift

The scan reports drift, resources that are up to date, skipped resources without a saved configuration, and errors. Use --context to scan a different state context.

6. State Locking

When a state context is active, resource-changing commands hold its S3 lock until the AWS operation and state update finish. If a command leaves a stale lock, confirm that no operation is still running before removing it:

ecsctl state unlock --force

See the Remote State guide for context setup, imports, drift checks, and lock recovery.

---

Global Flags

The following flags can be passed to any subcommand to override default configurations:

Flag	Description
--region	AWS region (overrides environment variables and configurations)
--profile	AWS profile to authenticate with
--context	Named state context to use (overrides active context in local config)

Build & Test

make test-floci uses dummy test credentials and a local Floci endpoint; it does not need an AWS account or real AWS keys. The current Floci ECS API does not list the Express Gateway operations, so Floci covers the standard ECS service lifecycle. A manually dispatched AWS Express smoke workflow creates, waits for, describes, and deletes a one-task service. It uses GitHub OIDC through the AWS_SMOKE_ROLE_ARN secret, verifies the expected AWS account before creating resources, and requires ECS infrastructure/execution roles; leave the cluster input blank to create and remove a temporary cluster. See the Floci ECS support matrix.

make build     # builds binary to ./bin/ecsctl
make test      # runs unit tests
make test-floci # runs ECS integration test against local Floci (requires Docker Compose or Podman)
make lint      # runs golangci-lint checking
make clean     # cleans up build outputs and binaries

Contributing

Contributions are welcome. See CONTRIBUTING.md for development guidance, commit message rules, pull request review, and CI checks.