Metadata-Version: 2.4
Name: nano-whale
Version: 0.1.15
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. Built with [Textual](https://textual.textualize.io/), Nano Whale provides an elegant, keyboard-driven interface for Docker management without the overhead of Docker Desktop.

## 📸 Screenshots

### Main Interface
<p align="center">
  <img src="./imgs/main.png" alt="Nano Whale Main Interface" width="100%">
</p>

### Multi-Select Operations
<p align="center">
  <img src="./imgs/multi_select.png" alt="Multi-Select Mode" width="100%">
</p>

### Command Panel
<p align="center">
  <img src="./imgs/commands_panel.png" alt="Commands Panel" width="100%">
</p>

### Logs - In Shell
<p align="center">
  <img src="./imgs/in_shell_logs.png" alt="In-Shell Logs" width="100%">
</p>

### Logs - New Terminal Window
<p align="center">
  <img src="./imgs/new_shell_logs.png" alt="Logs in New Terminal" width="100%">
</p>

### Terminal (Exec) - In Shell
<p align="center">
  <img src="./imgs/in_shell_exec_terminal.png" alt="In-Shell Terminal Exec" width="100%">
</p>

### Terminal (Exec) - New Window
<p align="center">
  <img src="./imgs/new_shell_terminal.png" alt="Terminal in New Window" width="100%">
</p>

---

## ✨ Features

### 🖥️ Split-Pane Interface
- **Left Pane**: Three stacked tables showing Containers, Images, and Volumes simultaneously
- **Right Pane**: Detailed view with 5 tabbed panels for container inspection
- **Bottom Panel**: Real-time log output and status messages

### 📦 Container Management
- Start, stop, and restart containers
- View container logs (in-shell or new terminal window)
- Launch interactive terminal sessions (exec into containers)
- Delete containers with safety checks (stops running containers first)

### 🖼️ Image Management
- View all Docker images with size and creation info
- Delete unused images
- Multi-select for batch deletion

### 💾 Volume Management
- List all Docker volumes
- Delete volumes (with force option)
- Batch operations support

### 🔍 Container Inspection (Right Pane Tabs)
| Tab | Content |
|-----|---------|
| **Info (1)** | Container ID, Image, Status, PID, Exit Code, Platform, Hostname, Restart Policy |
| **Env (2)** | All environment variables |
| **Ports (3)** | Port mappings (host → container) |
| **Volumes (4)** | Volume mounts with source, destination, and mode |
| **Networks (5)** | Network configuration, IP addresses, gateways, MAC addresses |

### ⚡ Additional Features
- 🚀 **Lightning Fast** - Minimal resource footprint
- ⌨️ **Keyboard-Driven** - Full keyboard navigation
- 🖱️ **Mouse Support** - Click anywhere on a table section to switch
- 📦 **Multi-Select** - Batch operations on multiple items
- 🔄 **Auto-Refresh** - Manual refresh with `A` key
- 🧹 **Smart Prune** - Two-step confirmation for system cleanup
- 🎨 **Visual Feedback** - Highlighted labels show active table
- 🌐 **Cross-Platform** - Windows (WSL), Linux, macOS support

---

## 📋 Prerequisites

- **Python 3.8+**
- **Docker Engine** installed and running
- For Windows: **WSL2** with Docker (or Docker Desktop)

### Platform Support

| Platform | Docker Command |
|----------|---------------|
| Windows (WSL2) | `wsl docker ...` |
| Linux | `docker ...` |
| macOS | `docker ...` |

---

## 📦 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
pip install -e .
```

---

## 🚀 Usage

Simply run:

```bash
nano-whale
```

Or run directly:

```bash
python main.py
```

---

## ⌨️ Keyboard Shortcuts

### Table Navigation
| Key | Action |
|-----|--------|
| `C` | Switch to **Containers** table |
| `I` | Switch to **Images** table |
| `V` | Switch to **Volumes** table |
| `↑/↓` | Navigate rows |
| `Page Up/Down` | Fast scroll |
| `Home/End` | Jump to first/last row |
| **Mouse Click** | Click anywhere on table section to switch |

### Detail Panel Tabs
| Key | Action |
|-----|--------|
| `1` | **Info** tab - Container details |
| `2` | **Env** tab - Environment variables |
| `3` | **Ports** tab - Port mappings |
| `4` | **Volumes** tab - Volume mounts |
| `5` | **Networks** tab - Network configuration |

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

### Logs & Terminal
| Key | Action |
|-----|--------|
| `L` | View **Logs** in-shell (suspends TUI) |
| `Ctrl+L` | View **Logs** in new terminal window |
| `T` | Launch **Terminal** in-shell (exec) |
| `Ctrl+T` | Launch **Terminal** in new window |

### Multi-Select & Batch Operations
| Key | Action |
|-----|--------|
| `M` | **Mark/Unmark** current item |
| *(then)* `S/X/R/D` | Perform action on all marked items |

### Utilities
| Key | Action |
|-----|--------|
| `A` | **Refresh** all tables |
| `G` | Toggle **Stats** display in container list |
| `P` | **Prune** menu (press twice to confirm) |
| `Q` | **Quit** application |

---

## 📖 Usage Examples

### Viewing Container Details

1. Launch Nano Whale: `nano-whale`
2. First container is automatically selected and details shown
3. Press `1-5` to switch between Info, Env, Ports, Volumes, Networks tabs
4. Use `↑/↓` to select different containers

<p align="center">
  <img src="./imgs/main.png" alt="Container Details View" width="100%">
</p>

### Starting Multiple Containers

1. Press `C` to ensure Containers table is focused
2. Press `M` on first container to mark it `[*]`
3. Press `↓` then `M` to mark more containers
4. Press `S` to start all marked containers

<p align="center">
  <img src="./imgs/multi_select.png" alt="Multiple Containers Marked" width="100%">
</p>

### Viewing Live Logs

**In-Shell (suspends TUI):**
1. Select a running container
2. Press `L`
3. Logs stream in terminal
4. Press `Ctrl+C` to return to TUI

<p align="center">
  <img src="./imgs/in_shell_logs.png" alt="In-Shell Logs" width="100%">
</p>

**In New Window:**
1. Select a running container
2. Press `Ctrl+L`
3. New terminal window opens with streaming logs
4. TUI remains active

<p align="center">
  <img src="./imgs/new_shell_logs.png" alt="Logs in New Terminal" width="100%">
</p>

### Exec into Container

**In-Shell:**
1. Select a running container
2. Press `T`
3. Interactive shell opens
4. Type `exit` to return to TUI

<p align="center">
  <img src="./imgs/in_shell_exec_terminal.png" alt="In-Shell Terminal" width="100%">
</p>

**In New Window:**
1. Select a running container
2. Press `Ctrl+T`
3. New terminal with shell opens

<p align="center">
  <img src="./imgs/new_shell_terminal.png" alt="Terminal in New Window" width="100%">
</p>

### Cleaning Up System

1. Press `P` - shows warning notification
2. Press `P` again within 5 seconds to confirm
3. Executes `docker system prune -a -f`
4. Removes all unused containers, images, and volumes

### Switching Between Tables

**Keyboard:**
- `C` → Containers
- `I` → Images  
- `V` → Volumes

**Mouse:**
- Click anywhere within a table's yellow border area

**Key Benefits:**
- ✅ No Docker Desktop required (on Windows with WSL2)
- ✅ Direct Docker Engine access
- ✅ Minimal overhead
- ✅ Works over SSH

---

## 🔧 Configuration

Nano Whale auto-detects your platform:

| Platform | Detection | Command Prefix |
|----------|-----------|----------------|
| Windows + WSL | `wsl` available | `wsl docker` |
| Windows (native) | No WSL | `docker` |
| Linux | `platform.system()` | `docker` |
| macOS | `platform.system()` | `docker` |

---

## 🐛 Troubleshooting

### "wsl command not found" (Windows)

```bash
wsl --install
# Restart computer after installation
```

### "Cannot connect to Docker daemon"

**Linux/macOS:**
```bash
sudo systemctl start docker
# or
sudo service docker start
```

**Windows WSL:**
```bash
wsl sudo service docker start
```

### "Permission denied"

```bash
sudo usermod -aG docker $USER
# Then log out and back in
```

### Terminal commands not opening new windows

Nano Whale tries multiple terminal emulators:
- **Windows**: Windows Terminal (`wt.exe`), `cmd.exe`
- **Linux**: `gnome-terminal`, `konsole`, `xfce4-terminal`, `xterm`
- **macOS**: Terminal.app, iTerm2

Ensure at least one is installed and accessible in PATH.

---

## 🤝 Contributing

Contributions welcome! 

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

# Setup
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

# Run
python main.py
```

---

## 📜 License

MIT License - see [LICENSE](LICENSE) file.

---

## 🙏 Acknowledgments

- Built with [Textual](https://textual.textualize.io/) by Textualize.io
- Inspired by lazydocker and the need for a lightweight alternative

---

## ⭐ Star History

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

---

**Made with ❤️ by Vriddhachalam S**

*Swim fast, stay light! 🐳*