Metadata-Version: 2.4
Name: lazyssh
Version: 1.4.2
Summary: A comprehensive SSH toolkit for managing connections and tunnels
Author-email: Bochner <lazyssh@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Bochner/lazyssh
Project-URL: Bug Tracker, https://github.com/Bochner/lazyssh/issues
Project-URL: Documentation, https://github.com/Bochner/lazyssh
Project-URL: Source Code, https://github.com/Bochner/lazyssh
Keywords: ssh,tunnel,proxy,socks,terminal,connection,management
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama>=0.4.6
Requires-Dist: rich>=13.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: pexpect>=4.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: prompt_toolkit<3.1.0,>=3.0.39
Requires-Dist: wcwidth>=0.2.5
Requires-Dist: art>=5.9
Requires-Dist: paramiko>=3.0.0
Requires-Dist: tomli-w>=1.0.0
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# LazySSH

A comprehensive SSH toolkit for managing connections, tunnels, and remote sessions with a modern CLI interface.

![LazySSH](https://raw.githubusercontent.com/Bochner/lazyssh/main/lazyssh.png)

## Overview

LazySSH simplifies SSH connection management with an elegant CLI interface. It helps you manage multiple connections, create tunnels, transfer files, and automate common SSH tasks.

### Key Features

- **Interactive Command Interface**: Smart command mode with tab completion and guided workflows
- **Connection Management**: Handle multiple SSH connections with control sockets
- **Saved Configurations**: Save and reuse connection configurations with TOML-based storage
- **Tunneling**: Create forward and reverse tunnels with simple commands
- **Dynamic Proxy**: Set up SOCKS proxy for secure browsing
- **SCP Mode**: Transfer files securely with rich visualization and progress tracking
- **Terminal Integration**: Open terminal sessions directly with runtime method switching
- **Wizard Workflows**: Guided interactive workflows for complex operations
- **Rich Visual Elements**: Color coding, progress bars, and tree visualizations

## Quick Start

### Installation

```bash
# Install globally
pip install lazyssh

# Or with pipx (recommended)
pipx install lazyssh

# Or install for the current user only
pip install --user lazyssh
```

### Basic Usage

```bash
# Start LazySSH
lazyssh

# Create a new connection
lazyssh> lazyssh -ip 192.168.1.100 -port 22 -user admin -socket myserver

# Create a connection with dynamic SOCKS proxy
lazyssh> lazyssh -ip 192.168.1.100 -port 22 -user admin -socket myserver -proxy 8080

# Create a tunnel
lazyssh> tunc myserver l 8080 localhost 80

# Open a terminal
lazyssh> open myserver

# Transfer files (SCP mode)
lazyssh> scp myserver

# Use wizard for guided workflows
lazyssh> wizard lazyssh
lazyssh> wizard tunnel

# In SCP mode: visualize remote directory tree
scp myserver:/home/user> tree

# Download files
scp myserver:/home/user> get config.json
```

## Documentation

For detailed documentation, please see the [docs directory](docs/):

- [User Guide](docs/user-guide.md): Comprehensive guide to using LazySSH
- [Command Reference](docs/commands.md): Details on all available commands
- [SCP Mode Guide](docs/scp-mode.md): How to use the file transfer capabilities
- [Tunneling Guide](docs/tunneling.md): Creating and managing SSH tunnels
- [Troubleshooting](docs/troubleshooting.md): Common issues and solutions
- [Development Guide](docs/development.md): Information for contributors
- [Publishing Guide](docs/publishing.md): How to publish the package

## Requirements

- Python 3.11+
- OpenSSH client

### Optional Dependencies

- **Terminator terminal emulator** - For opening terminals in external windows. If not installed, LazySSH will use a native terminal that runs in the current terminal window.

### Platform Support

LazySSH is compatible with:
- **Linux** - Full support
- **macOS** - Full support

**Windows Users:** Windows OpenSSH does not support SSH master mode (`-M` flag) which is required for LazySSH's persistent connection functionality. Windows users should use [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) to run LazySSH with full functionality.

## Terminal Methods

LazySSH supports two methods for opening SSH terminal sessions:

### Native Terminal (Default)
The native terminal method runs SSH as a subprocess in your current terminal window. This requires no external dependencies and works out of the box. **Important:** You can exit the SSH session (using `exit` or `Ctrl+D`) and return to LazySSH without closing the SSH connection, allowing you to manage multiple sessions easily.

### Terminator Terminal
If you have Terminator installed, LazySSH can open SSH sessions in new Terminator windows. This is useful if you want to keep multiple terminals open simultaneously.

### Configuration

You can control which terminal method to use either at runtime or via environment variable:

**Runtime configuration (recommended):**
```bash
# From command mode
lazyssh> terminal native      # Set terminal method to native
lazyssh> terminal auto        # Set terminal method to auto
lazyssh> terminal terminator  # Set terminal method to terminator
```

**Environment variable:**
```bash
# Automatically select best available method (default)
# Tries Terminator first, falls back to native
export LAZYSSH_TERMINAL_METHOD=auto

# Force native terminal (runs in current window)
export LAZYSSH_TERMINAL_METHOD=native

# Force Terminator (requires Terminator to be installed)
export LAZYSSH_TERMINAL_METHOD=terminator
```

**Default behavior (auto):**
- If Terminator is installed: Opens terminals in new Terminator windows
- If Terminator is not installed: Uses native terminal in current window
- Falls back gracefully if the preferred method fails

**Features:**
- Native terminal allows returning to LazySSH after exiting the SSH session
- Terminal method can be changed at runtime without restarting LazySSH
- Terminal method is displayed in the SSH connections status table

## Saved Connection Configurations

LazySSH allows you to save connection configurations for quick reuse. Configurations are stored securely in TOML format at `/tmp/lazyssh/connections.conf` with owner-only permissions (600).

### Saving Connections

After creating a successful connection, LazySSH will prompt you to save it:

```bash
lazyssh> lazyssh -ip server.example.com -port 22 -user admin -socket myserver
# After connection succeeds
Save this connection configuration? (y/N): y
Enter config name [myserver]: prod-server
✓ Configuration saved as 'prod-server'
```

Or save manually from command mode:

```bash
lazyssh> save-config prod-server
```

### Using Saved Configurations

**View saved configurations:**
```bash
lazyssh> config
# Displays table of all saved configurations
```

**Connect using a saved configuration:**
```bash
lazyssh> connect prod-server
```

**Delete a saved configuration:**
```bash
lazyssh> delete-config prod-server
```

### Configuration File Format

Configurations are stored in TOML format at `/tmp/lazyssh/connections.conf`:

```toml
[prod-server]
host = "server.example.com"
port = 22
username = "admin"
ssh_key = "/home/user/.ssh/id_rsa"

[dev-server]
host = "192.168.1.100"
port = 2222
username = "developer"
proxy_port = 9050
```

### Security Considerations

- **File Permissions**: Config file is automatically set to mode 600 (owner read/write only)
- **Location**: Files are stored in `/tmp/lazyssh/` which is cleared on system reboot
- **SSH Keys**: Only paths to SSH keys are stored, not the keys themselves
- **Sensitive Data**: Consider using SSH keys instead of password authentication
- **Manual Editing**: You can safely edit the TOML file directly if needed

### CLI Flag

View configurations at startup:

```bash
lazyssh --config
```

Or specify a custom config file path:

```bash
lazyssh --config /path/to/custom/connections.conf
```

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
