ssmctl

A lightweight CLI for managing AWS SSM connections, remote command execution, and file transfers — designed to feel like a modern SSH/SCP replacement powered by AWS Systems Manager.

---

Contents

• Features
  • list
  • connect
  • run
  • cp upload
  • cp download
  • version
• Targets
• Global Flags
• Installation
• Requirements
• Target OS support
• Design Goals
• Project Structure
• Roadmap
• Contributing
• Contributors
• License

---

Features

List instances

ssmctl list [--filter <substring>] [--platform linux|windows]

Lists all EC2 instances managed by AWS Systems Manager. Instance IDs, Name tags, platform, agent version, and ping status are displayed as a table. Use --output json for structured output.

INSTANCE ID           NAME        PLATFORM   AGENT VERSION   STATUS
i-0123456789abcdef0   web-1       Linux      3.2.2086.0      Online
i-0987654321fedcba0   bastion-1   Linux      3.2.2086.0      Online
i-0aabbccddeeff0011   win-app-1   Windows    3.2.2086.0      Offline

Filter examples:

# Substring match on Name tag
ssmctl list --filter web

# Filter by platform
ssmctl list --platform linux
ssmctl list --platform windows

# JSON output
ssmctl list --output json

Requires ssm:DescribeInstanceInformation and ec2:DescribeInstances permissions.

---

Connect to an instance

ssmctl connect <target>

Starts an interactive SSM session. Requires the AWS Session Manager plugin.

---

Run a command

ssmctl run <target> -- <command>

Example:

ssmctl run web-1 -- uname -a

Stdout and stderr are streamed to your terminal. The exit code of the remote command is propagated.

---

Upload a file

ssmctl cp ./file.txt <target>:/tmp/file.txt

Note: uploads are limited to ~2 MB (SSM SendCommand document size).

---

Download a file

ssmctl cp <target>:/var/log/app.log ./app.log

Note: downloads are limited to ~36 KB (SSM GetCommandInvocation output size).

---

Show version

ssmctl version

---

Targets

A <target> can be:

• An EC2 instance ID — i-0123456789abcdef0
• An EC2 Name tag — web-1

Resolution strategy:

• Input starting with i- is treated as an instance ID directly.
• Everything else is looked up via the EC2 Name tag.

---

Global Flags

--profile, -p   AWS profile (defaults to AWS_PROFILE env var)
--region,  -r   AWS region
--output,  -o   Output format: text | json  (default: text)
--debug,   -d   Enable debug logging
--timeout, -t   Timeout for remote commands (default: 60s)

---

Installation

Download a release binary (recommended)

Pre-built binaries for Linux, macOS (Intel + Apple Silicon), and Windows are attached to every GitHub release.

# Example — adjust version and platform as needed
curl -L https://github.com/rhysmcneill/ssmctl/releases/latest/download/ssmctl-linux-amd64 \
  -o /usr/local/bin/ssmctl && chmod +x /usr/local/bin/ssmctl

Homebrew (macOS / Linux)

brew tap rhysmcneill/ssmctl
brew install ssmctl

---

Requirements

• AWS credentials configured (environment variables, ~/.aws/credentials, or an IAM role)
• The target EC2 instance must have the SSM Agent installed and running
• For connect, the Session Manager plugin must be installed locally

---

Target OS support

Command	Linux/macOS targets	Windows targets
connect	Supported	Supported when the Session Manager plugin is installed locally
run	Supported via AWS-RunShellScript	Not currently supported; Windows targets require AWS-RunPowerShellScript
cp	Supported	Not currently supported; transfers rely on POSIX utilities such as cat and base64

The run and cp commands currently build shell commands for POSIX-like targets. When EC2 metadata identifies a Windows target, these commands return a clear unsupported-target error instead of running a shell command that would fail remotely. Use connect for Windows targets, or run PowerShell commands through AWS Systems Manager directly until ssmctl gains native Windows command and transfer support.

---

Design Goals

• Simple, ergonomic CLI (inspired by ssh and scp)
• No SSH keys or open inbound ports required
• Built entirely on AWS SSM
• Works with existing AWS credentials and config
• Scriptable via --output json

---

Project Structure

ssmctl/
├── cmd/ssmctl/          # binary entry point
├── e2e/                 # end-to-end tests
├── internal/
│   ├── app/             # application wiring (AWS client setup)
│   ├── cmd/             # Cobra command definitions
│   ├── config/          # flag validation and configuration
│   ├── output/          # text / JSON output formatting
│   ├── ssm/             # SSM and EC2 API calls
│   └── version/         # build-time version variables
├── tools/release/       # release-please configuration
├── go.mod
└── go.sum

---

Roadmap

• connect via SSM Session Manager
• run command execution via SendCommand
• cp upload (local → remote)
• cp download (remote → local)
• target resolution (instance ID + Name tag)
• structured output (text / json)
• timeout + context handling
• basic error handling and validation
• Homebrew formula
• ssmctl list — instance discovery with filtering (#50)
• shell completion (bash, zsh, fish)
• --output json support for connect

---

Contributing

See CONTRIBUTING.md.

---

License

MIT License

---

Contributors

Thanks to everyone who has contributed to ssmctl!

---