sshcli: A Modern SSH Config Manager

sshcli is a command-line tool for exploring, managing, and tidying your SSH configuration files. It provides a rich set of commands to list, search, edit, and tag your hosts, making it easy to handle complex SSH setups without manually editing config files.

It is built on top of sshcore and serves as a sibling tool to sshui, a graphical frontend with similar capabilities.

!sshcli-demo

Key Features

• Host Management: Add, edit, remove, and copy Host blocks from any of your SSH config files.
• Powerful Listing & Searching: Quickly list all hosts or find specific ones with wildcard patterns and substring searches.
• Tagging System: Assign tags to hosts for better organization. Define custom colors for tags to make them stand out.
• Safe Edits: Automatically creates backups of your config file before making any changes.
• Backup Management: List, restore, and prune old backups with simple commands.
• Multi-Config Support: Manage multiple SSH config files (e.g., /etc/ssh/ssh_config, ~/.ssh/config, and ~/.ssh/config.d/*.conf) and treat them as a single source.
• SSH Key Utilities: Generate and inspect SSH key pairs directly from the CLI.
• Rich Formatting: Uses rich to provide clean, readable, and colorful terminal output.

Installation

Install sshcli directly from PyPI:

pip install ixlab-sshcli

This will install sshcli and its core engine, sshcore.

Usage

sshcli follows a standard COMMAND SUBCOMMAND structure. You can get help at any level:

sshcli --help
sshcli list --help
sshcli tag --help

Common Commands

Show Host Details

The default action is to show details for a host. This is a shortcut for sshcli show <host>.

# Show the most specific matching block for 'my-server'
sshcli my-server

# Show all blocks that match a wildcard pattern
sshcli 'bastion-*' --details

List and Find Hosts

# List all hosts in a compact table
sshcli list

# List hosts, showing their full patterns and source file
sshcli list --patterns --files

# Find hosts where the pattern or HostName contains 'prod'
sshcli find prod

# Find hosts with the 'web' tag
sshcli find web --tag web

Add, Edit, and Remove Hosts

# Add a new host block to the default config
sshcli add my-new-server --hostname 10.0.5.20 --user admin

# Add a host with a custom option
sshcli add jump-box -H 1.2.3.4 -u ec2-user -o "IdentityFile=~/.ssh/aws.pem"

# Edit an existing host to change its port
sshcli edit my-new-server --port 2222

# Remove an option from a host
sshcli edit jump-box --remove-option User

# Remove a host block entirely
sshcli remove my-new-server

Tagging

Tags help you organize hosts. First, define a tag with a color, then assign it.

# Define a 'prod' tag with a red color for the default config
sshcli tag color prod red

# Add the 'prod' tag to a server
sshcli tag add 'prod-db-*' prod

# List all hosts with the 'prod' tag
sshcli list --tag prod

# Remove a tag from a host
sshcli tag remove 'prod-db-1' prod

Managing Config Sources

sshcli can read from multiple SSH config files. By default it enables /etc/ssh/ssh_config and ~/.ssh/config, and if no active files exist it falls back to ~/.ssh/config.d/*.conf. You can manage these sources with the config-source command.

# List all configured source files
sshcli config-source list

# Add a new config file to be included
sshcli config-source add ~/.ssh/personal.conf

# Disable a source without removing it
sshcli config-source disable ~/.ssh/personal.conf

# Set the default target for commands like 'add' and 'edit'
sshcli config-source default ~/.ssh/work.conf

Backups

sshcli automatically backs up any file it modifies.

# List available backups for the default config
sshcli backup list

# Restore a config from a specific backup
sshcli backup restore 20231027120000

# Prune old backups, keeping only the 10 most recent
sshcli backup prune --keep 10

SSH Keys

# List all key pairs in the default key directory
sshcli key list

# Show detailed information about a specific key
sshcli key show my-key

# Generate a new 4096-bit RSA key pair
sshcli key add my-new-key --size 4096

Configuration

sshcli stores its own settings in ~/.ssh/sshcli.json (override with $SSHCLI_SETTINGS_PATH). This file contains:

• config_sources: A list of SSH config files to read, whether they are enabled, and which one is the default target for edits.
• tag_definitions: Global definitions for tags and their associated colors.

You typically won't need to edit this file by hand, as the config-source and tag color commands manage it for you.

Tag Metadata

Tag assignments and definitions are stored as special comments in your SSH config files, ensuring they remain human-readable and don't interfere with the SSH client.

# @tags: prod, web, nginx
Host prod-web-1
  HostName 10.1.1.10
  User www-data

# @tags: prod, db, postgres
Host prod-db-1
  HostName 10.1.2.20
  User postgres

Development

To set up a local development environment:

1. Clone the repository.
2. Create and activate a virtual environment.
3. Install the project in editable mode with development dependencies:

   pip install -e .[dev]

4. Run the test suite:

   pytest

License

This project is licensed under the MIT License.