ecsta
April 28, 2026 ยท View on GitHub
ecsta is an "ECS Task Assistant" tool.
Product status
Production ready.
Install
Homebrew
$ brew install fujiwara/tap/ecsta
Binary releases
Usage
Usage: ecsta <command>
Flags:
-h, --help Show context-sensitive help.
-c, --cluster=STRING ECS cluster name ($ECS_CLUSTER)
-r, --region=STRING AWS region ($AWS_REGION)
-o, --output="table" output format (table, tsv, json) ($ECSTA_OUTPUT)
-q, --task-format-query=STRING A jq query to format task in selector
($ECSTA_TASK_FORMAT_QUERY)
Commands:
configure
Create a configuration file of ecsta
describe
Describe tasks
exec
Execute a command on a task
list
List tasks
logs
Show log messages of a task
portforward --local-port=INT --remote-port=INT
Forward a port of a task
stop
Stop a task
trace
Trace a task
version
Show version
Configuration
ecsta is a zero configuration command. But you can use a configuration file (~/.config/ecsta/config.json) to set default options.
Run an interactive setting as below.
$ ecsta configure
$ ecsta configure --show
2022/08/08 15:36:54 configuration file: /home/fujiwara/.config/ecsta/config.json
{
"filter_command": "peco",
"output": "tsv"
}
List tasks
Usage: ecsta list
List tasks
Flags:
-f, --family=FAMILY Task definition family
-s, --service=SERVICE Service name
--output-tags Output tags of tasks
--tags=KEY=VALUE,... Show only tasks that have specified tags
$ ecsta list --cluster foo
| ID | TASKDEFINITION | INSTANCE | LASTSTATUS | DESIREDSTATUS | CREATEDAT | GROUP | TYPE |
+----------------------------------+--------------------+----------+------------+---------------+---------------------------+---------------------+---------+
| 38b0db90fd4c4b5aaff29288b2179b5a | ecspresso-test:499 | | RUNNING | RUNNING | 2022-08-05T09:59:27+09:00 | service:nginx-local | FARGATE |
| 4deeb701c49a4892b7de39a2d0df17e0 | ecspresso-test:499 | | RUNNING | RUNNING | 2022-08-06T00:12:50+09:00 | service:nginx-local | FARGATE |
$ ecsta list --cluster foo --output-tags --tags Env=prod
| ID | TASKDEFINITION | INSTANCE | LASTSTATUS | DESIREDSTATUS | CREATEDAT | GROUP | TYPE | TAGS |
+----------------------------------+--------------------+----------+------------+---------------+---------------------------+---------------------+---------+---------------------------+
| 38b0db90fd4c4b5aaff29288b2179b5a | ecspresso-test:499 | | RUNNING | RUNNING | 2022-08-05T09:59:27+09:00 | service:nginx-local | FARGATE | Env=prod,Name=nginx-local |
| 4deeb701c49a4892b7de39a2d0df17e0 | ecspresso-test:499 | | RUNNING | RUNNING | 2022-08-06T00:12:50+09:00 | service:nginx-local | FARGATE | Env=prod,Name=nginx-local |
Filtering tasks by family and service
The --family and --service flags are accepted by list, describe, exec, portforward, cp, stop, trace, and logs.
The AWS ListTasks API does not allow family and serviceName to be specified at the same time. When both flags are passed to ecsta, tasks are listed by family and then post-filtered as follows:
- Tasks belonging to the specified service are kept.
- Tasks not associated with any service (typically launched via
RunTask, e.g.ecspresso run) of the same family are kept. - Tasks belonging to other services that share the family are excluded.
This is useful when several ECS services share a single task definition family: passing both --family and --service returns only the tasks that belong to the specified service plus its standalone runs.
Describe task
Usage: ecsta describe
Describe tasks
Flags:
--id=STRING task ID
--family=FAMILY task definition family name
--service=SERVICE ECS service name
Exec task
Usage: ecsta exec
Execute a command on a task
Flags:
--id=STRING task ID
--command="sh" command to execute
--container=STRING container name
--family=FAMILY task definition family name
--service=SERVICE ECS service name
Portforward task
--local-port and --remote-port, or -L is required.
Usage: ecsta portforward
Forward a port of a task
Flags:
--id=STRING task ID
--container=STRING container name
--local-port=INT local port
--remote-port=INT remote port
--remote-host=STRING remote host
-L, --L=STRING short expression of local-port:remote-host:remote-port
--family=FAMILY task definition family name
--service=SERVICE ECS service name
An example of port forwarding. Forward a port 8080 of a task to 80 of example.com.
$ ecsta portforward --local-port 8080 --remote-port 80 --remote-host example.com
$ ecsta portforward -L 8080:example.com:80
ecsta connects to the task and starts a port forwarding. You can access the port 8080 of the local machine.
$ curl -H"Host: example.com" http://localhost:8080
Stop task
Usage: ecsta stop
Stop a task
Flags:
--id=STRING task ID
--force stop without confirmation
--family=FAMILY task definition family name
--service=SERVICE ECS service name
Trace task
Run tracer. No need to install tracer command.
Usage: ecsta trace [flags]
Trace a task
Flags:
--id=STRING task ID
-d, --duration=1m duration to trace
--sns-topic-arn=STRING SNS topic ARN
--family=FAMILY task definition family name
--service=SERVICE ECS service name
-j, --json output JSON lines
Logs
Usage: ecsta logs
Show log messages of a task
Flags:
--id=STRING task ID
-s, --start-time=STRING a start time of logs
-d, --duration=1m log timestamps duration
-f, --follow follow logs
--container=STRING container name
--family=FAMILY task definition family name
--service=SERVICE ECS service name
-j, --json output as JSON lines
--start-time accepts flexible time formats (ISO8601, RFC3339, and etc). See also (tkuchiki/parsetime)[https://github.com/tkuchiki/parsetime].
When --start-time and --follow is specified both, --start-time may not work correctly.
copy files
Usage: ecsta cp <src> <dest> [flags]
Copy files from/to a task
Arguments:
<src> Source
<dest> Destination
Flags:
--port=12345 port number for file transfer
--[no-]progress show progress bar
--id=STRING task ID
--container=STRING container name
--family=FAMILY task definition family name
--service=SERVICE ECS service name
Example:
$ ecsta cp /path/to/file.txt _:/tmp/file.txt # copy file to a task(_ is the selected task)
$ ecsta cp 75dc060ef49b4ba1b2a33581dc5b876f:/tmp/file.txt /path/to/file.txt # copy file from the task.
ecsta cp copies files from/to a task.
How to work ecsta cp
ecsta cp works as below.
ecstastarts a temporary TCP server on the task vie ECS Exec.- The server listens on the specified port (default is 12345).
- tncl is used as the server. It is a tiny TCP server that like
nc -lcommand. - The server is terminated when the file transfer is completed.
ecstastarts a port forwarding to the temporary server.ecstaconnects to the temporary server via the port forwarding.ecstasends or receives a file via the connection.
Requirements:
- The task must have the ECS Exec feature enabled.
- The task must have
sh,base64, andchmodcommands.
Limitations:
- Multiple files and directories are not supported.
--task-format-query(-q) option
This option provides a formatter by jq query. The query processes tasks JSON (that output equals to ecsta describe) in task selector outputs.
For example,
$ ecsta -q '[(.tags[]|select(.key=="Env")|.value), .launchType] | @tsv' exec
A task selector output will be as below.
045a0639-1dc5-4d17-8101-2dd3fd339e91 prod EC2
8f431e68-a57d-41db-ae8d-5eb700a134dc dev FARGATE
The query [(.tags[]|select(.key=="Env")|.value), .launchType] | @tsv means,
"Show tags value of "Env" key, and LaunchType for tasks as TSV format.".