SSH Connector

A CLI tool to simplify SSH connections by providing an interactive menu of hosts from your ~/.ssh/config file.

Example

Let's assume your ~/.ssh/config file contains the following entries:

Host dev-app-1
    Hostname 192.168.1.10
    User devuser

Host dev-db-1
    Hostname 192.168.1.11
    User devuser

Host stg-app-1
    Hostname 192.168.2.10
    User stguser
    ProxyJump jump-stg

Host stg-db-1
    Hostname 192.168.2.11
    User stguser
    ProxyJump jump-stg

Host prod-app-1
    Hostname 10.0.0.10
    User produser
    ProxyJump jump-prod

Host prod-db-1
    Hostname 10.0.0.11
    User produser
    ProxyJump jump-prod

Host jump-dev
    Hostname 172.16.0.1
    User jumpdev

Host jump-stg
    Hostname 172.16.0.2
    User jumpstg

Host jump-prod
    Hostname 172.16.0.3
    User jumpprod

When you run ssh-connector, you will see an interactive menu like this:

      SSH Hosts
╔═════╤═════════════╗
║ No. │ Host        ║
╟─────┼─────────────╢
║ 1   │ dev-app-1   ║
║ 2   │ dev-db-1    ║
║ 3   │ stg-app-1   ║
║ 4   │ stg-db-1    ║
║ 5   │ prod-app-1  ║
║ 6   │ prod-db-1   ║
╚═════╧═════════════╝
     JUMP-HOSTS
╔═════╤═════════════╗
║ No. │ Host        ║
╟─────┼─────────────╢
║ 7   │ jump-dev    ║
║ 8   │ jump-stg    ║
║ 9   │ jump-prod   ║
╚═════╧═════════════╝
Enter the number or name of the host to connect to (or 'q' to quit, 'f' to filter):

You can select a host by entering its number (e.g., 5) or name (e.g., prod-app-1). The tool will execute the appropriate SSH command, handling ProxyJump automatically if configured.

Features

• Lists all hosts defined in your ~/.ssh/config, follows Include directives (e.g., Include ~/.ssh/config.d/*), and groups entries by source file (Main for the main config).
• Automatically separates hostnames containing jump (case-insensitive) into a dedicated "JUMP-HOSTS" table at the bottom with their source group.
• Ignores hosts whose names end with -abort or -ignore, or contain github/bitbucket (case-insensitive) so they do not appear in the menu.
• Allows you to select a host by number or name (case-insensitive) and filter by substring.
• Automatically connects to the selected host using the ssh command.

Installation

Prerequisites

• Python 3.13+
• uv (recommended) or pipx

Recommended: uv tool (global shim)

Creates an isolated environment and installs a shim (usually in ~/.local/bin) so you can run ssh-connector from any directory. Ensure that directory is on your PATH.

uv tool install .
ssh-connector --help

Alternative: uv pip (user install)

uv pip install . --user
ssh-connector --help

Alternative: pipx

pipx install .
ssh-connector --help

Development: editable install

If you are actively developing, install in editable mode so code changes are reflected immediately without reinstalling:

uv tool install -e .

Updating after local changes (non-editable)

If you installed without -e and want the ssh-connector shim to reflect code changes, reinstall it:

uv tool install --reinstall --no-cache .

Usage

Simply run the following command in your terminal:

ssh-connector

This will display a list of your configured SSH hosts. Enter a host number or name to connect.

How hosts are discovered and displayed

• The tool reads ~/.ssh/config and follows any Include directives it finds (globs are supported).
• If you want to split entries into ~/.ssh/config.d/, ensure your main config includes them, for example:

Include ~/.ssh/config.d/*

Host base
    HostName 192.168.0.10

• Hosts are grouped by the file they come from (Main for ~/.ssh/config, and the filename for included configs).
• Any host name containing jump (case-insensitive) is collected into a final "JUMP-HOSTS" section, with its source group shown in a separate column.
• Hosts whose names end with -abort or -ignore, or contain github/bitbucket, are filtered out entirely.
• You can type a host name directly (case-insensitive) instead of its number to connect.
• Press f to filter by substring (case-insensitive) before selecting a host.

Development

Setup

1. Clone the repository:

   git clone https://github.com/KKamJi98/ssh-connector.git
   cd ssh-connector
   

2. Sync dev dependencies with uv:

   uv sync --group dev
   

Running Tests

Run tests via uv:

uv run --group dev pytest -q

Formatting

This project uses ruff for linting and formatting.

# Lint
uv run --group dev ruff check .

# Format in-place
uv run --group dev ruff format

# Format check (CI-style)
uv run --group dev ruff format --check .

Commit Messages

This repository uses Conventional Commits and release-please. Use <type>: <summary> in English without scopes/emojis. See AGENTS.md for details.