CloudConsole

aws ssm send-command

Updated 16 November 2026 · How we write and check guides

Short answer

aws ssm send-command --document-name AWS-RunShellScript --instance-ids i-0123456789abcdef0 --parameters commands="uptime" runs a command on managed instances through Systems Manager Run Command, without SSH. It returns a CommandId straight away; fetch each instance's result with aws ssm get-command-invocation.

Terminal running cid=$(aws ssm send-command --document-name…
A worked example from this page. Copy commands from the text below, not from the image.

What the command does

Run Command sends an SSM document (a script template) to one or many managed nodes and collects their exit status and output. AWS-RunShellScript runs shell commands on Linux and macOS, AWS-RunPowerShellScript on Windows. Everything is logged in the Systems Manager command history and CloudTrail, which makes it a better audit trail than ad-hoc SSH.

Syntax

aws ssm send-command --document-name AWS-RunShellScript \
  (--instance-ids i-... | --targets Key=tag:<k>,Values=<v>) \
  --parameters 'commands=["cmd1","cmd2"],executionTimeout=["600"]' \
  [--comment "..."] [--max-concurrency 10%] [--max-errors 1] \
  [--timeout-seconds <delivery-timeout>] \
  [--cloud-watch-output-config CloudWatchOutputEnabled=true]

Worked examples

Run a quick diagnostic on one instance and read the output:

cid=$(aws ssm send-command --document-name AWS-RunShellScript \
  --instance-ids i-0123456789abcdef0 \
  --parameters 'commands=["df -h /","free -m","uptime"]' \
  --comment "INC-1234 disk check" \
  --query Command.CommandId --output text)
aws ssm wait command-executed --command-id "$cid" --instance-id i-0123456789abcdef0
aws ssm get-command-invocation --command-id "$cid" --instance-id i-0123456789abcdef0 \
  --query "[Status,StandardOutputContent,StandardErrorContent]" --output text

Restart a service on every instance tagged role=web, a quarter of the fleet at a time, stopping after two failures:

aws ssm send-command --document-name AWS-RunShellScript \
  --targets Key=tag:role,Values=web \
  --parameters 'commands=["sudo systemctl restart nginx"]' \
  --max-concurrency 25% --max-errors 2 \
  --comment "Restart nginx after config push"

Summary per instance for a multi-target command:

aws ssm list-command-invocations --command-id "$cid" \
  --query "CommandInvocations[].[InstanceId,Status]" --output table

Keep full output in CloudWatch Logs instead of the truncated console copy:

aws ssm send-command --document-name AWS-RunShellScript \
  --instance-ids i-0123456789abcdef0 \
  --parameters 'commands=["journalctl -u app --since \"1 hour ago\""]' \
  --cloud-watch-output-config CloudWatchOutputEnabled=true,CloudWatchLogGroupName=/ssm/run-command

Reading the status

StatusMeaning
Pending / InProgressDelivered or running
SuccessThe script exited with code 0
FailedNon-zero exit code; read StandardErrorContent
TimedOutHit the execution timeout, or never started within the delivery timeout
UndeliverableThe instance is not reachable by Systems Manager
CancelledStopped with aws ssm cancel-command

Key options

OptionNotes
--instance-ids / --targetsExplicit IDs, or tag-based targeting (Key=tag:Env,Values=prod) for fleets.
--parametersDocument parameters. For AWS-RunShellScript: commands, optional workingDirectory and executionTimeout (seconds, default 3600).
--timeout-secondsDelivery timeout: how long to wait for the command to start on an instance. Not the run time.
--max-concurrency, --max-errorsRate control for fleets: number or percentage.
--output-s3-bucket-nameWrite complete output to S3.

Gotchas

  • Output is truncated in the API response (to roughly 24,000 characters for standard output). Use S3 or CloudWatch output for anything long.
  • Commands run as root on Linux. That is convenient and dangerous; review what you send, especially to tag-based targets.
  • Quoting is two layers deep: shell quoting for the CLI, then JSON-ish list syntax for commands. Put complex scripts in a file and use --parameters file://params.json.
  • Unreachable instances show Undeliverable or time out; they have the same prerequisites as Session Manager.
  • The waiter is short. aws ssm wait command-executed gives up after about 100 seconds; for longer commands poll get-command-invocation yourself.

Questions

How do I see the output of aws ssm send-command?

Call aws ssm get-command-invocation --command-id <id> --instance-id <id> and read StandardOutputContent. For many instances, list-command-invocations --details shows output for each.

How do I run a command on all instances with a tag?

Use --targets Key=tag:<TagKey>,Values=<value> instead of --instance-ids, with --max-concurrency and --max-errors to control the rollout.

What is the difference between send-command and start-session?

send-command runs a non-interactive script and collects the result, on one or many instances. start-session gives you an interactive shell or port forward on a single instance.

When this happens away from your desk

Running a command across a fleet is powerful enough to deserve a second look before it goes out. CloudConsole, a phone app for AWS, is built with production guardrails for exactly that kind of change.

About the app → · Download on the App Store

Sources