Metadata-Version: 2.4
Name: nano-whale
Version: 0.1.12
Summary: A lightweight Terminal User Interface (TUI) for managing Docker containers, images, and volumes via WSL2
Project-URL: Homepage, https://github.com/Vriddhachalam/nano-whale.git
Project-URL: Repository, https://github.com/Vriddhachalam/nano-whale.git
Project-URL: Issues, https://github.com/Vriddhachalam/nano-whale/issues
Project-URL: Documentation, https://github.com/Vriddhachalam/nano-whale/blob/main/README.md
Author-email: Vriddhachalam S <svriddhachalam@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Vriddhachalam S
        
        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.
License-File: LICENSE
Keywords: cli,containers,docker,terminal,textual,tui,wsl2
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
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: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Requires-Dist: textual>=0.40.0
Description-Content-Type: text/markdown

# 🐳 Nano Whale - Lightweight Docker TUI

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Textual](https://img.shields.io/badge/built%20with-Textual-cyan.svg)](https://textual.textualize.io/)

A blazingly fast, lightweight **Terminal User Interface (TUI)** for managing Docker containers, images, and volumes via WSL2. Built with [Textual](https://textual.textualize.io/), Nano Whale provides an elegant, keyboard-driven interface for Docker management without the overhead of Docker Desktop.

<p align="center">
  <img src="https://via.placeholder.com/800x450/1e1e1e/00ff00?text=Nano+Whale+TUI+Demo" alt="Nano Whale TUI Screenshot">
</p>

## ✨ Features

- 🚀 **Lightning Fast** - Minimal resource footprint, native WSL2 integration
- ⌨️ **Keyboard-Driven** - Navigate and manage Docker resources without touching your mouse
- 📦 **Multi-Select Operations** - Perform batch operations on multiple containers/images/volumes
- 📊 **Real-Time Monitoring** - Live container status updates and log streaming
- 🎨 **Beautiful TUI** - Clean, intuitive interface built with Textual
- 🔄 **Quick Switching** - Toggle between containers, images, and volumes instantly
- 🧹 **Smart Cleanup** - Built-in prune commands for system maintenance
- 🪶 **Ultra-Lightweight** - Zero dependencies except Textual and WSL2

## 🎯 Why Nano Whale?

Tired of Docker Desktop's resource consumption? Nano Whale gives you:

- **No GUI Overhead** - Terminal-based means minimal memory usage
- **WSL2 Native** - Direct integration with Docker Engine in WSL2
- **Keyboard Efficiency** - Faster than clicking through GUI menus
- **SSH-Friendly** - Works perfectly over SSH connections
- **Open Source** - Free and community-driven

## 📋 Prerequisites

- **Windows 10/11** with WSL2 installed
- **Docker Engine** running in WSL2 (not Docker Desktop)
- **Python 3.8+**

### Quick WSL2 & Docker Setup

If you don't have WSL2 and Docker Engine set up:

```bash
# Install WSL2
wsl --install

# After restart, install Docker in WSL
wsl
sudo apt update
sudo apt install docker.io -y
sudo service docker start
```

## 📦 Installation

### Via pip (Recommended)

```bash
pip install nano-whale
```

### Via pipx (Isolated)

```bash
pipx install nano-whale
```

### From Source

```bash
git clone https://github.com/yourusername/nano-whale.git
cd nano-whale/docker_clui
pip install -e .
```

## 🚀 Usage

Simply run the command:

```bash
nano-whale
```

## ⌨️ Keyboard Shortcuts

### Navigation & Modes
| Key | Action |
|-----|--------|
| `C` | Switch to **Containers** view |
| `I` | Switch to **Images** view |
| `V` | Switch to **Volumes** view |
| `A` | **Refresh** current view |
| `↑/↓` | Navigate through list |

### Container Operations
| Key | Action |
|-----|--------|
| `S` | **Start** selected container(s) |
| `X` | **Stop** selected container(s) |
| `R` | **Restart** selected container(s) |
| `L` | View **Logs** for container |
| `D` | **Delete** selected item(s) |

### Multi-Select
| Key | Action |
|-----|--------|
| `M` | **Mark/Unmark** current item for batch operations |
| `M` (multiple) | Select multiple items, then perform action |

### Cleanup & Maintenance
| Key | Action |
|-----|--------|
| `P` | Open **Prune** menu (containers/images/volumes) |
| `P` (twice) | Confirm and execute **full system prune** |

### General
| Key | Action |
|-----|--------|
| `Q` | **Quit** application |

## 📖 Usage Examples

### Starting Multiple Containers

1. Press `C` to enter Containers view
2. Press `M` on first container to mark it
3. Press `↓` to move to next container
4. Press `M` to mark second container
5. Press `S` to start all marked containers

### Viewing Container Logs

1. Navigate to desired container with `↑/↓`
2. Press `L` to stream logs
3. Logs appear in the bottom panel
4. Navigate away to stop streaming

### Cleaning Up Unused Images

1. Press `I` to switch to Images view
2. Press `P` to open prune menu
3. Select "Prune Unused Images"
4. Confirm deletion

### Full System Cleanup

1. Press `P` once to prepare prune
2. Press `P` again within 3 seconds to confirm
3. All unused containers, images, and volumes will be removed

## 🎨 Interface Overview

```
┌─────────────────────────────────────────────────────────────┐
│ 🐳 Nano Whale - Docker TUI                                  │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  CONTAINER ID    IMAGE           STATUS      PORTS          │
│  ───────────────────────────────────────────────────────    │
│  abc123def456    nginx:latest    Up 2 hours  80->80         │
│  789ghi012jkl    postgres:15     Up 1 day    5432->5432     │
│  mno345pqr678    redis:alpine    Exited      -              │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│ Status: Container abc123def456 started successfully         │
│ Multi-select: 2 items marked                                │
└─────────────────────────────────────────────────────────────┘
 Q: Quit | A: Refresh | C: Containers | I: Images | V: Volumes
```

## 🏗️ Architecture

Nano Whale executes Docker commands through WSL2:

```
nano-whale (Python/Textual)
    ↓
wsl docker <command>
    ↓
Docker Engine (WSL2)
    ↓
Your Containers/Images/Volumes
```

This architecture means:
- **No Docker Desktop required**
- **Direct engine access**
- **Minimal overhead**
- **Maximum performance**

## 🔧 Configuration

Nano Whale uses `wsl docker` commands by default. If your setup is different, you can modify the command prefix in the source.

## 🤝 Contributing

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

### Development Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/nano-whale.git
cd nano-whale/docker_clui

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

# Run from source
python -m docker_clui.app
```

## 🐛 Troubleshooting

### "wsl command not found"

Install WSL2:
```bash
wsl --install
```

### "Cannot connect to Docker daemon"

Start Docker in WSL:
```bash
wsl sudo service docker start
```

### "Permission denied"

Add your user to the docker group:
```bash
wsl sudo usermod -aG docker $USER
```

Then restart your WSL session.

### Commands not working from Windows terminal

Prefix commands with `wsl`:
```bash
wsl docker ps
wsl docker images
```

## 📜 License

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

## 🙏 Acknowledgments

- Built with [Textual](https://textual.textualize.io/) by Textualize.io
- Inspired by the need for a lightweight Docker Desktop alternative
- Thanks to the Docker and WSL2 teams for their excellent tools

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/nano-whale/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/nano-whale/discussions)
- **Email**: svriddhachalam@gmail.com

## 🗺️ Roadmap

- [ ] Docker Compose support
- [ ] Container stats dashboard (CPU, Memory, Network)
- [ ] Custom color themes
- [ ] Export/Import container configurations
- [ ] Remote Docker host support
- [ ] Container shell access (exec)
- [ ] Network management
- [ ] Volume backup/restore

## ⭐ Star History

If you find Nano Whale useful, please consider giving it a star on GitHub!

---

**Made with ❤️ by Vriddhachalam S**

*Swim fast, stay light! 🐳*