gossm is an interactive CLI tool that lets you select servers in AWS and connect to them or transfer files using start-session, ssh, or scp through AWS Systems Manager Session Manager.
gossm is an interactive CLI tool that integrates with AWS Systems Manager Session Manager.
It helps you select EC2 instances with the AWS SSM agent installed and connect to them using start-session or ssh.
You can also transfer files using scp.
With gossm, there's no need to open inbound port 22 on your EC2 instances for SSH or SCP access.
AWS Systems Manager Session Manager uses SSH protocol tunneling for secure communication.
mfacommand to authenticate through AWS MFA and save temporary credentials in $HOME/.aws/credentials_mfa (default expiration: 6 hours)fwdcommand for local port forwarding to remote servicesfwdremcommand for forwarding to a secondary host through an SSM-connected instancecmdcommand to execute shell commands on multiple instances at once
- EC2 instances must have the AWS SSM agent installed
- Instances need the AmazonSSMManagedInstanceCore IAM policy attached
- For ssh/scp functionality, AWS SSM agent version 2.3.672.0 or later is required
- Configured AWS credentials
- IAM permissions for:
ec2:DescribeInstancesssm:StartSessionssm:TerminateSessionssm:DescribeSessionsssm:DescribeInstanceInformationssm:DescribeInstancePropertiesssm:GetConnectionStatus
- Recommended: Permission for
ec2:DescribeRegionsfor region selection
Homebrew is not supported yet.
Download the latest release from the releases page.
| Argument | Description | Default |
|---|---|---|
| -p, --profile | AWS profile name to use | default or $AWS_PROFILE |
| -r, --region | AWS region to connect to | Interactive selection if not specified |
If no profile is specified, gossm will first check for the AWS_PROFILE environment variable and then fall back to the default profile.
If no region is specified, you can select one through the interactive CLI.
When in an interactive session (start, ssh, or scp), you can use the following escape sequence:
- Enter followed by
~.- Disconnect from the session (useful when network connection is stuck)
This works the same way as the standard SSH escape sequence and provides a way to terminate sessions when network connectivity is lost. The tilde character (~) is only special when typed immediately after pressing Enter. Using ~ anywhere else (like ~/ for home directory or ~username) works normally.
Start an interactive terminal session with an EC2 instance.
$ gossm start
$ gossm start -t i-1234567890abcdef0 # Connect to a specific instanceConnect to an instance via SSH through AWS SSM.
# Interactive instance and user selection
$ gossm ssh
# Using a specific identity file
$ gossm ssh -i ~/.ssh/key.pem
# Direct SSH command
$ gossm ssh -e "ec2-user@i-1234567890abcdef0"
$ gossm ssh -e "-i key.pem ec2-user@i-1234567890abcdef0"
Transfer files to/from instances via SCP through AWS SSM.
# Transfer a local file to the remote server
$ gossm scp -e "localfile.txt ec2-user@i-1234567890abcdef0:/home/ec2-user/"
# Transfer a remote file to local machine
$ gossm scp -e "-i key.pem ec2-user@i-1234567890abcdef0:/remote/path/file.txt local.txt"Execute commands on one or more instances simultaneously.
# Run a command on interactively selected instances
$ gossm cmd -e "uptime"
# Run a command on a specific instance
$ gossm cmd -e "ls -la" -t i-1234567890abcdef0Forward a local port to a port on the remote EC2 instance.
# Interactive selection
$ gossm fwd
# With specific ports
$ gossm fwd -z 8080 -l 9090 # Remote port 8080 -> Local port 9090
$ gossm fwd -z 8080 # Remote port 8080 -> Local port 8080Forward a local port to a secondary remote host through an EC2 instance.
# Forward local port to a remote host through an EC2 instance
$ gossm fwdrem -z 5432 -l 5432 -a internal-db.example.comAuthenticate with MFA and save temporary credentials for use with AWS CLI and other tools.
# Authenticate with MFA code
$ gossm mfa 123456
# Set custom expiration time (in seconds)
$ gossm mfa -d 43200 123456 # 12 hours
# For AWS CLI to use these credentials, set in your shell profile:
export AWS_SHARED_CREDENTIALS_FILE=$HOME/.aws/credentials_mfa
gossm automatically manages the AWS Session Manager plugin for you:
- By default, it will download the latest version of the plugin on first use
- You can specify a specific plugin version by setting the
GOSSM_PLUGIN_VERSIONenvironment variable - If download fails, it will use the embedded plugin as a fallback
This project is licensed under the MIT License - see the LICENSE file for details.