ssm-run-cli 0.1.0

Run commands/scripts on EC2 via AWS SSM Run Command

ssm-run

Run shell commands or scripts on EC2 instances via AWS Systems Manager (SSM) Run Command.

Features

• Resolve targets by:
  • EC2 instance ID (i-...)
  • Name tag / hostname / FQDN
  • Private/Public IPv4
• Target expansion:
  • myserver{600..605}
• Run:
  • Inline command (-- "uptime")
  • Local script file (--file ./cmd.sh)
• SSM online filtering (with opt-out)
• Parallel result collection for faster output fetch
• Optional S3-backed full output (--s3-bucket) to avoid API truncation
• Debug mode to inspect exact remote command (--debug-command)

Installation

From PyPI

pip install ssm-run

Upgrade

pip install --upgrade ssm-run

From source (repo)

git clone https://wwwin-github.cisco.com/skumble/ssm-cli.git
cd ssm-cli
pip install .

Requirements

• Python 3.9+
• AWS credentials configured (profile/role/SSO)
• IAM permissions for:
  • ec2:DescribeInstances
  • ssm:DescribeInstanceInformation
  • ssm:SendCommand
  • ssm:ListCommandInvocations
  • ssm:GetCommandInvocation
• If using --s3-bucket:
  • instance role needs s3:PutObject
  • caller credentials need s3:GetObject

CLI Usage

ssm-run [OPTIONS] <target> [<target> ...] -- "<command>"
ssm-run [OPTIONS] <target> [<target> ...] --file ./script.sh
ssm-run [OPTIONS] -f hosts.txt -- "<command>"
ssm-run [OPTIONS] -f hosts.txt --file ./script.sh

Options

• -r, --region <region> AWS region (supports shortcuts: use1, euw1, aps1)
• -f, --hosts-file <file> Read targets from file (one per line, # comments allowed)
• --file <script.sh> Run local script file instead of inline command
• --batch-size <1..50> Instances per SendCommand call
• --timeout-seconds <sec> Global wait timeout
• --poll-interval <sec> Poll interval
• --no-online-filter Skip SSM online filtering
• --only-failed Print output only for failed instances
• --s3-bucket <bucket> Store/fetch full output from S3
• --s3-prefix <prefix> Optional S3 key prefix
• --debug-command Print decoded command and exit
• --max-workers <n> Parallel workers for output fetching
• -h, --help Help

Examples

1. Simple inline command

ssm-run --region euw1 myserver{600..605} -- 'uptime'

2. From hosts file

ssm-run -r use1 -f hosts.txt -- 'df -h'

3. Complex command using script file (recommended)

echo 'sudo grep -m1 "HUMIDITY" /mnt/logs/webex-api-streams.log' > cmd.sh
ssm-run --region euw1 myserver{600..605} --file cmd.sh

4. Long-running command with higher timeout

ssm-run --region euw1 --timeout-seconds 300 myserver{600..605} --file cmd.sh

5. Avoid output truncation using S3

ssm-run --region euw1 --s3-bucket my-ssm-logs myserver{600..605} --file cmd.sh

6. Validate what would run (no execution)

ssm-run --region euw1 --debug-command myserver601 -- 'uptime'

Notes on Quoting

For commands with JSON, nested quotes, pipes, or shell special characters, prefer --file instead of inline -- "<command>". This avoids local shell quoting issues before the command reaches the instance.

Exit Behavior

• Returns non-zero on major failures (for example: AWS API errors, no valid targets).
• Prints per-instance status and summary with success/failed/skipped/timeout counts.

Development

Build wheel/sdist:

python -m pip install --upgrade build
python -m build

Install local build:

python -m pip install --force-reinstall dist/*.whl

Publishing (maintainers)

python -m pip install --upgrade twine
python -m twine check dist/*
python -m twine upload dist/*

Versioning and Release Notes

• Versioning follows Semantic Versioning (MAJOR.MINOR.PATCH).
• Update version in pyproject.toml before each release.
• Add release notes in CHANGELOG.md.

First Public Release Checklist

1. Confirm package name availability on PyPI (ssm-run).
2. Verify metadata in pyproject.toml (name/version/urls/classifiers).
3. Build artifacts:

python -m pip install --upgrade build
python -m build
python -m twine check dist/*

4. Test local install from built wheel:

python -m pip install --force-reinstall dist/*.whl
ssm-run --help

5. Publish:

python -m twine upload dist/*

6. Tag release in git (example):

git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

License

Add your project license here (for example: MIT, Apache-2.0, or internal Cisco license).