Metadata-Version: 2.4
Name: ssm-connect
Version: 1.0.4
Summary: Interactive CLI to connect to AWS EC2 via SSM or SSH-over-SSM, with keyword search and multi-session terminal launch.
Author-email: Siby Jose <jose.siby@icloud.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/JoseSiby/ssm-connect
Project-URL: Issues, https://github.com/JoseSiby/ssm-connect/issues
Project-URL: Source, https://github.com/JoseSiby/ssm-connect
Keywords: aws,ec2,ssm,ssh,cli,session-manager,devops,cloud,sre,operations,infrastructure
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.26.0
Dynamic: license-file

# ssm-connect

Interactive CLI to connect to AWS EC2 instances and RDS databases via:

- **SSM Session Manager** (interactive shell)
- **SSH over SSM** (with your SSH key)
- **RDS Port Forwarding** (via EC2 bastion host)

Multiple sessions in parallel (each opens in a new terminal). Keyword search across Name, Instance ID, and all tag values. Simple, cross-platform, and secure-by-default.

## Features

- **Target Selection**: Choose to connect to EC2 instances or RDS databases
- **EC2 Connections**:
  - SSM Session Manager (interactive shell)
  - SSH over SSM (with private key authentication)
- **RDS Connections**:
  - Port forwarding to RDS databases via EC2 bastion host
  - Auto-selects available local port
- **Smart Search**: Filter instances by keywords (matches Name, InstanceId, and all tag values)
- **Multi-Session**: Opens each connection in a new terminal window (Linux, macOS, Windows) allowing for multiple simultaneous sessions.
- **AWS Session**: Automatically inherits AWS credentials

## Install

Latest release from PyPI: pip install --upgrade ssm-connect

Run the tool: ssm-connect


## Requirements

- **User should already be logged in to AWS**
- **AWS CLI v2**
- **SSM Session Manager plugin** ([installation guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html))
- **OpenSSH client** (`ssh` command) - for SSH over SSM
- **Python 3.8+**
- **Appropriate IAM role**


### Terminal Apps

The tool automatically detects and uses available terminal emulators:

- **Windows**: Windows Terminal (`wt`), PowerShell, or `cmd`
- **macOS**: Terminal.app
- **Linux**: `gnome-terminal`, `konsole`, `xterm`, or `x-terminal-emulator`


## Usage

Start the CLI: ssm-connect


### Connection Flow

1. **Choose Target Type**:
   - `[1] EC2` - Connect directly to an EC2 instance
   - `[2] RDS` - Forward port to an RDS database via bastion

2. **For EC2 Connections**:
   - Choose connection type:
     - `[1] SSM` - Interactive shell via Session Manager
     - `[2] SSH over SSM` - SSH session with your private key
   - Filter and select target EC2 instance
   - For SSH: Provide private key path and username

3. **For RDS Connections**:
   - **Step 1**: Select EC2 bastion instance (must have SSM access)
   - **Step 2**: Select target RDS database
   - Connect to `localhost:[auto-selected-port]` with your database client


## Troubleshooting

### Command not found
Ensure `aws`, `session-manager-plugin`, and `ssh` are installed and on PATH.

### SSO expired
Refresh your AWS SSO session: aws sso login --profile your-profile

### SSH key errors
Ensure the key exists and has proper permissions

### No terminal found (Linux)
Install a terminal emulator

### RDS connection refused
Ensure:
- The bastion EC2 instance has network connectivity to the RDS
- The bastion is running
- You have the appropriate role


## Uninstall
pip uninstall ssm-connect


## Contributing

Issues and pull requests are welcome. Please keep changes focused and include brief notes if behavior changes.


## License

Apache License 2.0. See LICENSE for details.
