@hadesgod/sshx/README.md

A modern CLI tool for managing SSH connections with interactive host selection and port forwarding capabilities.

# SSHX

A modern CLI tool for managing SSH connections with interactive host selection and port forwarding capabilities.

## Quick Start

```bash
# Using npx
npx @hadesgod/sshx

# Using npm
npm i -g @hadesgod/sshx
sshx

# Using bun
bun x @hadesgod/sshx
```



## Features

- 🔍 Interactive SSH host selection from your SSH config
- 🔄 Port forwarding setup with guided prompts
- 📋 Automatic command copying to clipboard
- 🎯 Support for custom ports and configurations
- 🚀 Built with TypeScript and Effect for robust error handling

## Usage Examples

### Basic SSH Connection
```bash
$ sshx
? Select a host to connect to my-server
# Copies: ssh my-server
```

### SSH with Port Forwarding
```bash
$ sshx
? Select a host to connect to database-server
? Do you want to set up port forwarding? Yes
? Enter the remote port (e.g. 5432) for forwarding 5432
? Enter the local port (e.g. 5432) for forwarding 8432
# Copies: ssh -L 8432:localhost:5432 database-server
```

### SSH with Custom Port
```bash
$ sshx
? Select a host to connect to custom-port-server
# Copies: ssh -p 2222 custom-port-server
```

## How It Works

When you run SSHX, it will:
1. Read your SSH config file (~/.ssh/config)
2. Present an interactive host selector
3. Offer port forwarding configuration if needed
4. Copy the final SSH command to your clipboard

## Development

### Prerequisites

- [Bun](https://bun.sh) v1.2.17 or later
- Node.js and npm (for development)

### Setup

```bash
# Install dependencies
bun install

# Build the project
bun run build

# Run in development mode
bun run dev
```

### Project Structure

```
src/
├── config/     # SSH config parsing and types
├── ssh/        # SSH command execution
├── ui/         # Interactive CLI components
└── utils/      # Utility functions
```

### Tech Stack

- [Bun](https://bun.sh) - JavaScript runtime and package manager
- [Effect](https://effect.website) - Functional programming library
- [@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js) - Interactive CLI prompts
- [TypeScript](https://www.typescriptlang.org/) - Type safety and developer experience

## Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines

- Follow TypeScript best practices
- Use Effect for error handling and functional programming patterns
- Maintain consistent code style using Biome
- Write meaningful commit messages

### Testing

> Note: Unit testing is currently in progress and will be improved in future updates. Contributions to test coverage are highly appreciated.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.