ixlab-sshcli 1.0.0
Command-line explorer for SSH configs built on sshcore.
License: MIT
Requires Python: >=3.10
Keywords: ssh, cli, config

# 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 <!-- Replace with an actual demo GIF -->

## 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:

```bash
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:

```bash
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>`.

```bash
# 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

```bash
# 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

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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

```bash
# 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.

```sshconfig
# @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:
    ```bash
    pip install -e .[dev]
    ```
4.  Run the test suite:
    ```bash
    pytest
    ```

## License

This project is licensed under the MIT License.