<div align="center">

# 🚀 OmniHost

### High-Performance SSH Management CLI for DevOps Engineers

[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

Manage hundreds of servers with lightning-fast parallel execution, beautiful CLI output, and DevOps-focused shortcuts.

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Contributing](#-contributing)

</div>

---

## ⚡ Highlights

```bash
# Quick start
omnihost --version              # Check version
omnihost examples               # See usage examples

# Server Groups - organize your infrastructure
omnihost group add web web01 web02 web03
omnihost exec-group web "systemctl restart nginx"
omnihost exec-group web "uptime" --dry-run  # Preview first!

# Command Aliases - reduce repetitive typing
omnihost alias add restart-nginx "sudo systemctl restart nginx"
omnihost exec-group web restart-nginx

# File Transfer - push/pull files easily
omnihost push web01 ./app.tar /opt/app/
omnihost pull db01 /var/log/mysql.log ./logs/
omnihost push web01 ./dist /var/www/ --recursive

# Execute on all servers in parallel - 10x faster, with retry & dry-run
omnihost exec-all "systemctl status nginx" --parallel 10 --retries 2 --dry-run
omnihost exec-all "uptime" --json | jq '.succeeded'  # CI/CD integration

# Quick DevOps shortcuts - no need to type full exec commands
omnihost uptime  # Uses default server
omnihost disk web01
omnihost memory db01

# Beautiful, formatted output with Rich library
omnihost list  # Stunning table view of all servers

# Enhanced logging for troubleshooting
omnihost --verbose exec web01 "ls -la"
omnihost --debug exec-all "uptime"

# Audit logging - all commands tracked automatically
cat ~/.omnihost/audit.log  # JSON audit trail
```

## 🎯 Why OmniHost?

| Problem | Traditional Approach | OmniHost |
|---------|---------------------|----------|
| Check 20 servers | 20 × 3s = 60 seconds | 12 seconds (parallel) |
| Type repetitive commands | `ssh user@host 'uptime'` | `omnihost uptime` |
| Manage server configs | Edit `~/.ssh/config` manually | Interactive `omnihost add` |
| View command output | Plain text | Beautiful formatted panels |
| Execute on multiple servers | Write bash loops | `omnihost exec-all` |

## ✨ Features

### 🖥️ Server Management
- **Add/Edit/Remove** servers with interactive prompts
- **List** all configured servers with beautiful table view
- **Info** command with connection testing
- Integrates with SSH config (`~/.ssh/config`)

### ⚡ Performance Features
- **Parallel execution** on multiple servers (5-20x faster)
- **Bulk operations** (`exec-all`, `exec-multi`)
- **Quick commands** for common DevOps tasks
- **Default server** configuration (no need to specify every time)
- **Connection pooling** and caching

### 🎨 Beautiful CLI
- Rich formatted output with colors and panels
- Progress bars for bulk operations
- Interactive prompts with validation
- Clean, organized command structure

### 🔐 Security
- SSH key authentication support
- No password storage
- Respects SSH config security settings
- Connection timeout management

## 📦 Installation

### From Source

```bash
# Clone the repository
git clone https://github.com/sagar.memane/omnihost.git
cd omnihost

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install
pip install -e .
```

### Requirements

- Python 3.8 or higher
- SSH access to remote servers
- SSH keys configured (recommended)

## 🚀 Quick Start

### 1. Add Your First Server

```bash
omnihost add
# Follow interactive prompts
```

Or use command-line options:
```bash
omnihost add -a web01 -h 192.168.1.100 -u ubuntu --key ~/.ssh/id_rsa
```

### 2. List Servers

```bash
omnihost list           # Basic view
omnihost list -v        # Verbose with SSH keys
```

### 3. Set Default Server (Optional)

```bash
omnihost config set-default web01
# Now you can use: omnihost uptime (without specifying server)
```

### 4. Execute Commands

```bash
# Single server
omnihost exec web01 "df -h"

# All servers (parallel)
omnihost exec-all "uptime"

# Specific servers
omnihost exec-multi "web01,web02,db01" "systemctl status nginx"
```

### 5. Quick DevOps Commands

```bash
omnihost uptime web01          # Quick uptime
omnihost disk web01            # Disk usage
omnihost memory web01          # Memory usage
omnihost processes web01       # Top processes
omnihost status web01 nginx    # Service status
omnihost logs web01 nginx      # View logs
```

### 6. Interactive Shell

```bash
omnihost connect web01
# Full PTY support - run vim, htop, top, etc.
```

## 📖 Documentation

- **[Quick Reference](docs/QUICK_REFERENCE.md)** - Command cheat sheet
- **[Performance Guide](docs/PERFORMANCE.md)** - DevOps patterns and optimization
- **[Architecture](docs/ARCHITECTURE.md)** - Code structure and design
- **[Contributing](CONTRIBUTING.md)** - Development guide
- **[Security](SECURITY.md)** - Security policy
- **[Changelog](CHANGELOG.md)** - Version history

## 🎯 Common Use Cases

### Daily Operations
```bash
# Morning health check
omnihost exec-all "uptime && free -h" --parallel 10

# Check disk space across infrastructure
omnihost exec-all "df -h /" --no-output | grep "9[0-9]%"
```

### Deployments
```bash
# Deploy to web servers
omnihost exec-multi "web01,web02,web03" \
  "cd /app && git pull && systemctl restart app" --parallel 3

# Verify deployment
omnihost exec-multi "web01,web02,web03" "curl -s localhost/health"
```

### Troubleshooting
```bash
# Quick diagnostics
omnihost memory prod01
omnihost processes prod01
omnihost logs prod01 nginx -n 100

# Check all servers for issues
omnihost exec-all "systemctl is-failed --quiet || echo 'Services OK'"
```

## 🏗️ Project Structure

```
omnihost/
├── __init__.py              # Package metadata  
├── cli.py                   # CLI entry point
├── config.py                # Configuration management
├── ssh_config.py            # SSH config operations
├── ssh_client.py            # Connection management
├── performance.py           # Caching & optimization
└── commands/                # Command modules
    ├── server_management.py # list, add, edit, remove, info
    ├── exec_command.py      # Remote execution
    ├── connect_command.py   # Interactive shell
    ├── bulk_operations.py   # exec-all, exec-multi
    ├── quick_commands.py    # Quick DevOps shortcuts
    └── config_command.py    # Configuration management
```

## 🤝 Contributing
- 📋 **Beautiful table formatting** for server lists
- ℹ️ **Server information** - View details and test connections
- 🔧 **SSH config integration** - Works with `~/.ssh/config`
- 🎨 **Rich formatting** - Color-coded output and panels
- 💾 **Persistent storage** - All config saved to SSH config file
- 🔐 **SSH key support** - Use identity files for authentication

## 📚 Commands Reference

| Command | Description | Example |
|---------|-------------|---------|
| `list` | Show all configured servers | `omnihost list -v` |
| `add` | Add a new server | `omnihost add -a web01 -h 1.2.3.4 -u ubuntu` |
| `info` | Show server details | `omnihost info myserver` |
| `edit` | Edit server configuration | `omnihost edit myserver` |
| `remove` | Remove a server | `omnihost remove myserver` |
| `exec` | Execute command on server | `omnihost exec myserver "ls -la"` |
| `connect` | Open interactive shell | `omnihost connect myserver` |

## 📂 Project Structure

```
ServerManager/
├── omnihost/                      # Main package
│   ├── __init__.py               # Package metadata
│   ├── cli.py                     # CLI entry point
│   ├── ssh_config.py              # SSH config operations
│   ├── ssh_client.py              # Connection management
│   ├── utils.py                   # Shared utilities
│   └── commands/                  # Command modules
│       ├── __init__.py
│       ├── server_management.py   # list, add, edit, remove, info
│       ├── exec_command.py        # Remote command execution
│       └── connect_command.py     # Interactive shell
├── pyproject.toml                 # Package configuration
├── requirements.txt               # Dependencies
├── main.py                        # Legacy wrapper
├── README.md                      # This file
├── ARCHITECTURE.md                # Developer guide
└── QUICK_REFERENCE.md             # Quick reference
```

## 🔧 Development

### Install in Development Mode
```bash
pip install -e .
```

Changes to the code are immediately reflected without reinstalling.

### Run Tests
```bash
# Syntax check
python -m py_compile omnihost/*.py omnihost/commands/*.py

# Test commands
omnihost --help
omnihost list
```

### Add New Commands

1. Create `omnihost/commands/my_command.py`
2. Import in `omnihost/cli.py`
3. Register with `register_my_command(app)`

See ARCHITECTURE.md for details.

## 🛠️ Requirements

- Python 3.8 or higher
- Unix-like system (Linux, macOS, WSL on Windows)
- SSH config file at `~/.ssh/config`

## 📝 SSH Config

OmniHost works with standard SSH config format:

```
Host myserver
    HostName 192.168.1.100
    User ubuntu
    Port 22
    IdentityFile ~/.ssh/id_rsa

Host production
    HostName prod.example.com
    User admin
    IdentityFile ~/.ssh/prod_key
```

OmniHost can create and manage this file for you!

## 🎨 Example Sessions

### Adding a Server
```bash
$ omnihost add
╭─────────────────╮
│ Add New Server  │
╰─────────────────╯
Server alias: web01
Hostname or IP address: 192.168.1.100
SSH username: ubuntu
SSH port [22]: 
Use SSH key file? [Y/n]: y
Path to private key [~/.ssh/id_rsa]: 

Configuration Summary:
  Alias: web01
  Hostname: 192.168.1.100
  User: ubuntu
  Port: 22
  Identity File: ~/.ssh/id_rsa

Add this server? [Y/n]: y
✓ Successfully added server 'web01'
```

### Listing Servers
```bash
$ omnihost list

            Configured Servers             
╭────────┬─────────────┬───────────┬──────╮
│ Alias  │ Hostname    │ User      │ Port │
├────────┼─────────────┼───────────┼──────┤
│ web01  │ 192.168.1.100│ ubuntu   │  22  │
│ db01   │ 10.0.0.5    │ postgres  │  22  │
╰────────┴─────────────┴───────────┴──────╯

Total servers: 2
```

### Executing Commands
```bash
$ omnihost exec web01 "df -h | head -5"

╭────────────────────── 🔌 Connecting ───────────────────────╮
│ Host: web01                                                 │
│ Server: ubuntu@192.168.1.100:22                            │
│ Command: df -h | head -5                                    │
╰─────────────────────────────────────────────────────────────╯

╭───────────────────── ✓ Output ─────────────────────────╮
│ Filesystem      Size  Used Avail Use% Mounted on       │
│ /dev/sda1        50G   20G   28G  42% /                │
│ tmpfs            16G     0   16G   0% /dev/shm          │
│ /dev/sdb1       100G   45G   51G  47% /data            │
╰─────────────────────────────────────────────────────────╯
```

## 🤝 Contributing

We love contributions! Here's how you can help:

1. **Star this repo** ⭐
2. **Report bugs** via GitHub Issues
3. **Suggest features** or improvements
4. **Submit Pull Requests** - see [CONTRIBUTING.md](CONTRIBUTING.md)

### Development Setup
```bash
git clone https://github.com/sagar.memane/omnihost.git
cd omnihost
python3 -m venv venv
source venv/bin/activate
pip install -e .
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## 📄 License

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

## 🙏 Acknowledgments

- Built with [Typer](https://typer.tiangolo.com/) - Modern CLI framework
- Styled with [Rich](https://rich.readthedocs.io/) - Beautiful terminal formatting  
- SSH via [Paramiko](http://www.paramiko.org/) - Pure Python SSH implementation

## 📮 Support

- **Issues**: [GitHub Issues](https://github.com/sagar.memane/omnihost/issues)
- **Discussions**: [GitHub Discussions](https://github.com/sagar.memane/omnihost/discussions)
- **Security**: See [SECURITY.md](SECURITY.md) for reporting vulnerabilities

## 🗺️ Roadmap

- [x] Server management (add, edit, remove, list)
- [x] Remote command execution
- [x] Interactive shell sessions
- [x] Bulk parallel operations
- [x] Quick DevOps shortcuts
- [ ] Server grouping and tagging
- [ ] Command history and replay
- [ ] Custom command templates
- [ ] SSH tunnel management
- [ ] File transfer operations (SCP/SFTP)
- [ ] Integration with cloud providers (AWS, Azure, GCP)
- [ ] Web UI for server management
- [ ] Ansible integration

## 📈 Performance Benchmarks

| Operation | Sequential | Parallel (--parallel 5) | Speedup |
|-----------|------------|------------------------|---------|
| 10 servers uptime | 30s | 6s | 5x |
| 20 servers status | 60s | 12s | 5x |
| 50 servers check | 150s | 30s | 5x |

*Tests conducted on servers with ~300ms average latency*

## 🆘 Troubleshooting

### Command not found after installation
```bash
source venv/bin/activate  # Activate virtual environment
pip install -e .  # Reinstall if needed
which omnihost  # Should show path in venv
```

### Connection issues
```bash
# Test SSH manually first
ssh -F ~/.ssh/config myserver

# Check server configuration
omnihost info myserver
```

### Permission errors with SSH keys
```bash
chmod 600 ~/.ssh/id_rsa
chmod 700 ~/.ssh
```

### Slow bulk operations
```bash
# Increase parallelism (default is 5)
omnihost exec-all "uptime" --parallel 10

# Reduce timeout for faster failure detection
omnihost exec-all "ping -c 1 google.com" --timeout 5
```

---

<div align="center">

**[⬆ back to top](#-omnihost)**

Made with ❤️ for DevOps Engineers

If you find OmniHost useful, please ⭐ star this repository!

</div>
