Metadata-Version: 2.4
Name: whisper-ssh
Version: 1.0.2
Summary: Whisper messages to remote Linux machines via SSH
Home-page: https://github.com/JdMasuta/whisper-ssh
Author: Josh Meesey
Maintainer: Josh Meesey
License: MIT License
        
        Copyright (c) 2024 Your Name
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/JdMasuta/whisper-ssh
Project-URL: Documentation, https://github.com/JdMasuta/whisper-ssh#readme
Project-URL: Repository, https://github.com/JdMasuta/whisper-ssh.git
Project-URL: Bug Tracker, https://github.com/JdMasuta/whisper-ssh/issues
Project-URL: Changelog, https://github.com/JdMasuta/whisper-ssh/blob/main/CHANGELOG.md
Keywords: ssh,notification,remote,desktop,linux,ubuntu,notify-send,whisper
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Communications
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fabric>=3.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: validators>=0.20.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Requires-Dist: pre-commit>=2.15; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: build>=0.8; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov>=2.0; extra == "test"
Requires-Dist: pytest-mock>=3.0; extra == "test"
Dynamic: home-page
Dynamic: license-file
Dynamic: platform
Dynamic: requires-python

# 📡 whisper-ssh

[![PyPI version](https://badge.fury.io/py/whisper-ssh.svg)](https://badge.fury.io/py/whisper-ssh)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Send desktop notifications to remote Linux machines via SSH with a beautiful, interactive command-line interface.

## ✨ Features

- 🎯 **Smart Host Management** - Automatic DNS resolution and SSH connectivity testing
- 👤 **User Management** - Remember users per host for quick selection
- 💬 **Flexible Messaging** - Preset messages plus custom message support
- 🔒 **Secure** - No password storage, secure SSH connections
- 🎨 **Beautiful Interface** - Rich terminal UI with colors and interactive menus
- 📦 **Easy Installation** - One command pip install
- ⚡ **Fast Setup** - Auto-configuring with sensible defaults

## 🚀 Quick Start

### Installation

```bash
pip install whisper-ssh
```

### Usage

```bash
# Interactive mode (recommended)
whisper-ssh

# Or use the short alias
whisper
```

### First Run

The tool will guide you through:

1. **Select Target Host** - Choose from known hosts or add a new one
2. **DNS Resolution** - Automatic hostname/IP resolution and validation
3. **Choose User** - Select from previous users or add new
4. **Enter Password** - Secure password input (never stored)
5. **Pick Message** - Choose from presets or write custom message
6. **Send!** - Notification appears on remote desktop

## 🎯 Use Cases

- **System Administration** - Notify users about maintenance, reboots, updates
- **Development Teams** - Notify about build completions, deployments
- **Remote Work** - Send meeting reminders, break notifications
- **Automation** - Integrate with scripts and monitoring systems

## 📖 Examples

### Basic Usage (Interactive)

```bash
$ whisper-ssh
```

### Programmatic Usage

```python
from remote_notify import RemoteNotificationManager

manager = RemoteNotificationManager()

# Send a notification
success = manager.send_notification(
    ip_address="192.168.1.100",
    username="john",
    password="secret",
    message="Build completed successfully!",
    title="CI/CD Pipeline"
)

if success:
    print("Notification sent!")
```

### Multiple Hosts

```python
# Send to multiple hosts at once
host_configs = [
    {"ip": "192.168.1.100", "username": "user1", "password": "pass1"},
    {"ip": "192.168.1.101", "username": "user2", "password": "pass2"},
]

results = manager.send_notification_to_multiple_hosts(
    host_configs=host_configs,
    message="System maintenance in 30 minutes",
    title="System Notice"
)
```

## 🔧 Configuration

Configuration is automatically stored in `~/.config/whisper-ssh/remote_notify_config.json`

### Configuration Structure

```json
{
  "hosts": {
    "server1": "192.168.1.100",
    "workstation": "10.0.0.50"
  },
  "users": {
    "server1": ["admin", "developer"],
    "workstation": ["user"]
  },
  "preset_messages": [
    "System maintenance starting in 30 minutes",
    "Please save your work and log off",
    "Meeting starting in 5 minutes"
  ]
}
```

### Built-in Preset Messages

- System maintenance notifications
- Reboot warnings
- Meeting reminders
- Break notifications
- Build/deployment status
- Security updates

## 🛠️ Requirements

### Local Machine

- Python 3.7+
- Network access to target machines

### Target Machines (Remote)

- Ubuntu/Linux with desktop environment
- SSH server running
- `libnotify-bin` package installed:
  ```bash
  sudo apt install libnotify-bin
  ```
- User logged into desktop session

## 🎨 Interface Features

### Interactive Menus

- ✅ Arrow key navigation
- ✅ Searchable host/user lists
- ✅ Colored output and status indicators
- ✅ Progress bars and loading indicators
- ✅ Error handling with helpful messages

### Management Features

- 📋 View all configuration
- ➕ Add/remove hosts and users
- 📝 Manage preset messages
- 🧪 Test connectivity
- 📤 Export/import configuration
- 🔄 Reset to defaults

## 🔒 Security

- **No Password Storage** - Passwords are never saved to disk
- **SSH Security** - Uses Fabric's secure SSH implementation
- **Input Validation** - Prevents shell injection attacks
- **Connection Testing** - Validates hosts before attempting connections

## 🐛 Troubleshooting

### Common Issues

**"Connection failed"**

- Verify SSH is running: `sudo systemctl status ssh`
- Check firewall: `sudo ufw status`
- Test manual connection: `ssh user@host`

**"Cannot resolve hostname"**

- Check DNS settings
- Try using IP address instead
- Verify network connectivity

**"Notification doesn't appear"**

- Ensure user is logged into desktop
- Check if Do Not Disturb is enabled
- Verify notify-send is installed: `which notify-send`

### Debug Mode

```python
# Enable verbose SSH output
manager = RemoteNotificationManager()
# Set hide=False in send_notification for debugging
```

## 🤝 Contributing

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

### Development Setup

```bash
# Clone the repository
git clone https://github.com/JdMasuta/whisper-ssh.git
cd whisper-ssh

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black whisper-ssh/
```

## 📝 License

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

## 🙏 Acknowledgments

- [Fabric](https://www.fabfile.org/) - High-level SSH library
- [Questionary](https://github.com/tmbo/questionary) - Interactive CLI prompts
- [Rich](https://github.com/Textualize/rich) - Beautiful terminal output
- [Validators](https://github.com/kvesteri/validators) - Input validation

## 🔗 Links

- **PyPI**: https://pypi.org/project/whisper-ssh/
- **GitHub**: https://github.com/JdMasuta/whisper-ssh
- **Issues**: https://github.com/JdMasuta/whisper-ssh/issues
- **Documentation**: https://github.com/JdMasuta/whisper-ssh#readme
