Metadata-Version: 2.4
Name: graphical-ssh
Version: 0.1.1
Summary: Graphical SSH client connection and configuration manager for Debian
Keywords: ssh,terminal,config,gui,pyqt,debian
Author: Greg Grace
Author-email: Greg Grace <ggrace@519lab.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Topic :: Terminals
Requires-Dist: pyqt6>=6.7
Requires-Dist: pyte>=0.8
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
Requires-Dist: pytest-qt>=4.4 ; extra == 'dev'
Requires-Dist: ruff>=0.6 ; extra == 'dev'
Requires-Python: >=3.12
Provides-Extra: dev
Description-Content-Type: text/markdown

# gssh

A graphical SSH client connection and configuration manager for Debian/Linux. Manage your `~/.ssh/config` hosts through a GUI, edit connection parameters, and open SSH sessions — either in an embedded terminal or by launching your preferred external terminal emulator.

## Features

- **Visual host management** — view, add, edit, and delete Host entries from `~/.ssh/config`
- **Dedicated fields** for the common options: HostName, User, Port, IdentityFile, ProxyJump, ForwardAgent
- **Extra options** — any arbitrary ssh_config directive via a freeform text area
- **Safe writes** — atomic file replacement with automatic timestamped backups (`.config.bak.YYYYMMDD_HHMMSS`) and `0600` permissions
- **Config linter** — catches unknown/deprecated options, insecure key permissions, invalid ports, undefined ProxyJump references, and pattern-overlap conflicts (first-match-wins)
- **Connection test** — TCP ping-before-connect with latency display
- **Wildcard hosts** — supports patterns like `*.lab.local`
- **Search/filter** — live filter by alias, hostname, or user
- **In-app terminal** — embedded PTY-based terminal using [pyte](https://github.com/selectel/pyte) for VT220 emulation with 5000-line scrollback and 16-colour ANSI
- **External terminal** — toggle to launch `ssh` in konsole, gnome-terminal, xterm, or any detected emulator
- **Round-trip safe** — preserves comments, preamble, and unknown directives

## Requirements

- Python 3.12+
- PyQt6
- pyte
- (Optional) a terminal emulator for external mode: konsole, gnome-terminal, xterm, etc.

## Install

### From PyPI (recommended)

```bash
pip install gssh
gssh
```

Or run without installing:

```bash
uvx gssh          # via uv
pipx run gssh     # via pipx
```

### From source

```bash
git clone https://github.com/ggrace519/graphical-ssh.git
cd graphical-ssh
uv sync
uv run gssh
```

### Desktop integration

To add gssh to your application menu:

```bash
# If installed via pip, the data files are inside the package:
python -c "import gssh.data; print(gssh.data.__path__)"
sudo cp $(python -c "import gssh.data; print(gssh.data.__path__[0])")/gssh.desktop /usr/share/applications/
sudo cp $(python -c "import gssh.data; print(gssh.data.__path__[0])")/gssh.svg /usr/share/icons/hicolor/scalable/apps/
sudo update-desktop-database
```

## Usage

```bash
# Use default ~/.ssh/config
uv run gssh

# Specify a custom config file
uv run gssh -c /path/to/ssh/config
```

### GUI controls

| Action | How |
|---|---|
| Add a host | **Add Host** button → fill in the dialog |
| Edit a host | Select row → **Edit** button (or double-click to connect) |
| Delete a host | Select row → **Delete** button → confirm |
| Connect | Select row → **Connect** (or double-click the row) |
| Toggle terminal mode | **In-App Terminal** / **External Terminal** toggle |
| Filter hosts | Type in the search bar |
| Save changes | **Save** button (writes to config file with backup) |
| Reload from disk | **Reload** button |

## Development

```bash
# Run tests with coverage
uv run pytest

# Run the app
uv run gssh

# Run with a test config
uv run gssh -c /tmp/test-config
```

## Project structure

```
src/gssh/
├── __init__.py       # package metadata
├── __main__.py       # CLI entry point (argparse + QApplication)
├── config.py         # SSH config parser/writer (round-trip safe, atomic writes)
├── models.py         # Qt table model for host entries
├── host_editor.py    # Add/Edit host dialog
├── connect.py        # SSH command builder + launch (in-app or external)
├── terminal.py       # In-app terminal widget (pyte + PTY)
└── main_window.py    # Main window: host list, toolbar, terminal container

tests/
└── test_config.py    # Parser/writer tests (20 tests, 90% config coverage)
```

## Roadmap

- **Tier 2:** key file management (generate, view, copy public key), known-hosts viewer, connection test, import/export
- **Tier 3:** port-forwarding manager, per-host tags/notes, system tray quick-connect

## License

MIT