# aws ecs execute-command

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws ecs execute-command --cluster my-cluster --task <task-id> --container web --interactive --command "/bin/sh" opens a shell inside a running container using ECS Exec. It only works if the task was started with execute-command enabled, the task role allows the SSM messages actions, and the Session Manager plugin is installed on your machine.

## What the command does

ECS Exec uses Systems Manager Session Manager under the hood. The ECS agent injects an SSM agent into the task when it starts, and `execute-command` opens an encrypted session to it, with no SSH, open ports or bastion host involved. It works for Fargate and EC2 launch types.

## Syntax

```
aws ecs execute-command --cluster my-cluster \
  --task <task-id-or-arn> \
  [--container <name>] \
  --interactive \
  --command "/bin/sh"
```

`--container` is required when the task has more than one container. Interactive mode is the only mode supported, so always pass `--interactive`.

## Prerequisites checklist

| Requirement | How to check or fix |
|---|---|
| Session Manager plugin installed locally | `session-manager-plugin --version`; install it from the AWS docs if missing. |
| Exec enabled on the task | `enableExecuteCommand` is true in `describe-tasks`. Enable on the service with `update-service --enable-execute-command --force-new-deployment`; existing tasks are not changed. |
| Task role permissions | The **task role** (not the execution role) needs `ssmmessages:CreateControlChannel`, `CreateDataChannel`, `OpenControlChannel` and `OpenDataChannel`. |
| Network path to SSM | Tasks in private subnets need a NAT gateway or an `ssmmessages` VPC interface endpoint. |
| Your permissions | `ecs:ExecuteCommand` on the task or cluster. |
| A shell in the image | Distroless and scratch images have no `/bin/sh`; run a specific binary instead. |

## Worked examples

**Shell into one task of a service**:

```
TASK=$(aws ecs list-tasks --cluster prod --service-name orders-api \
  --query "taskArns[0]" --output text)
aws ecs execute-command --cluster prod --task "$TASK" --container web \
  --interactive --command "/bin/sh"
```

**Run a single command** and return:

```
aws ecs execute-command --cluster prod --task "$TASK" --container web \
  --interactive --command "env"
```

**Check the agent is running** before trying:

```
aws ecs describe-tasks --cluster prod --tasks "$TASK" \
  --query "tasks[0].containers[].[name,managedAgents[?name=='ExecuteCommandAgent'].lastStatus | [0]]" \
  --output text
```

`RUNNING` is what you want. `STOPPED` or missing usually points at task role permissions or networking.

## Gotchas

- **`TargetNotConnectedException`** is the classic failure: almost always task role permissions, missing network route to SSM, or a task started before exec was enabled. See [TargetNotConnectedException](https://cloudconsole.dev/errors/ecs-execute-command-targetnotconnected).
- **Do not fix production by hand.** Changes made inside a container are lost when the task is replaced; use exec for diagnosis.
- **Auditing.** Configure the cluster's execute command logging to send session output to CloudWatch Logs or S3, and restrict `ecs:ExecuteCommand` with conditions on cluster or container name.
- **Quoting.** `--command` takes a single string; for pipes or redirects wrap it, for example `--command "sh -c 'ps aux | head'"`.
- **One session per call.** Each `execute-command` opens a fresh session, so scripts that need many commands are better served by one interactive shell, or by a one-off task with `run-task` that runs the whole script.

## Questions

### How do I exec into a Fargate container?

Enable execute command on the service or task, give the task role the ssmmessages permissions, install the Session Manager plugin, then run aws ecs execute-command with --interactive.

### Why does ECS execute-command say the execute command failed because execute command was not enabled?

The task was started without enableExecuteCommand. Turn it on for the service and force a new deployment so new tasks have it.

### Do I need SSH keys for ECS Exec?

No. It uses Session Manager over an encrypted channel and IAM for access control.

## When this happens away from your desk

Shelling into a container from a phone is possible but rarely pleasant. CloudConsole, a phone app for AWS, is built to show task status, stop reasons and logs on a phone, which often answers the question without a shell.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: ecs execute-command](https://docs.aws.amazon.com/cli/latest/reference/ecs/execute-command.html)
- [ExecuteCommand API reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ExecuteCommand.html)

## Related

- [How to exec into an ECS container](https://cloudconsole.dev/how-to/ecs-exec-into-container)
- [ECS Exec: TargetNotConnectedException when calling the ExecuteCommand operation](https://cloudconsole.dev/errors/ecs-execute-command-targetnotconnected)
- [aws ecs update-service](https://cloudconsole.dev/cli/ecs-update-service)
- [aws ecs list-tasks](https://cloudconsole.dev/cli/ecs-list-tasks)
- [aws ssm start-session](https://cloudconsole.dev/cli/ssm-start-session)
- [aws ecs describe-services](https://cloudconsole.dev/cli/ecs-describe-services)

---

Source: https://cloudconsole.dev/cli/ecs-execute-command

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
