ec2-tui 2.0.0

Interactive TUI for managing AWS EC2 SSH connections

EC2 Connect

A modern Terminal User Interface (TUI) for managing AWS EC2 instances — list, search, SSH, SCP, and scan servers across all regions.

Quick Install

Linux / macOS:

curl -sSL https://raw.githubusercontent.com/zb-ss/ec2-ssh/master/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/zb-ss/ec2-ssh/master/install.ps1 | iex

Or install directly via pipx / pip:

pipx install ec2-tui

Manual install from source:

git clone https://github.com/zb-ss/ec2-ssh.git
cd ec2-ssh
pipx install .

Features

• Interactive TUI with mouse and keyboard support powered by Textual
• List and search EC2 instances across all AWS regions
• SSH into instances — launches in new terminal window with auto-detected emulator
• Run remote commands via overlay panel with real-time streaming output
• Browse remote file systems — interactive file tree navigation
• SCP file transfer — upload/download files and directories
• Keyword-based server scanning — search file contents across instances
• Bastion host / jump server support via ProxyJump or ProxyCommand
• SSH key management with auto-discovery and per-instance configuration
• Instance caching with stale-while-revalidate for fast startup
• Fully configurable — all settings in ~/.ec2_ssh_config.json

Prerequisites

• Python 3.8+
• AWS CLI configured (~/.aws/credentials and ~/.aws/config)
• SSH client (standard on Linux/macOS, OpenSSH on Windows)
• pipx for isolated installation (recommended)

Your AWS credentials need ec2:DescribeInstances and ec2:DescribeRegions permissions.

Usage

ec2-ssh           # Launch the TUI
ec2-ssh --debug   # Launch with debug logging to stderr

Keyboard Shortcuts

Context	Key	Action
Global	Q	Quit
Global	?	Help screen
Global	Escape	Go back / close
Instance List	/	Focus search
Instance List	R	Force-refresh from AWS
Instance List	S	SSH to selected instance
Instance List	B	Browse remote files
Instance List	C	Run command overlay
Instance List	T	SCP transfer
Command Overlay	Ctrl+C	Stop running command
Command Overlay	Up/Down	Command history

What You Can Do

1. List Instances — View all EC2 instances with search/filter
2. Search — Filter instances by name, type, region, or state; search scan results
3. Manage SSH Keys — Configure default and per-instance SSH keys
4. Scan Servers — Run keyword scans across running instances
5. Settings — Configure connection profiles, scan rules, preferences

When you select a server: browse files, run commands, SSH connect, SCP transfer, or view scan results.

Instance Caching

Scenario	Behavior
First launch (no cache)	Fetches from AWS with progress indicator
Restart within TTL (default 1h)	Instant load from cache
Restart after TTL	Shows stale data immediately, refreshes in background
Press R	Force-refresh from AWS

Configuration

All configuration lives in ~/.ec2_ssh_config.json, created automatically on first run.

See Configuration Guide for the full reference including connection profiles, scan rules, and match conditions.

Development

# Run directly (primary dev workflow)
PYTHONPATH=src python3 -m ec2_ssh.main

# Run with debug logging
PYTHONPATH=src python3 -m ec2_ssh.main --debug

# Install editable
pip install -e .

# Update pipx installation after changes
pipx install . --force

# Run tests
pip install -e ".[test]"
pytest

See Architecture for codebase structure and design patterns.

Troubleshooting

See Troubleshooting Guide for help with SSH connections, bastion hosts, key management, and AWS credentials.

Logging

Logs are always written to ~/.ec2_ssh_logs/ec2_ssh.log. Use --debug for verbose stderr output.

When SSH fails, the terminal window stays open showing the error and exit code.

License

This project is licensed under the MIT License — see the LICENSE file for details.