WhaleTUI - Docker CLI Dashboard

A terminal-based Docker management tool inspired by k9s, providing an intuitive and powerful interface for managing Docker containers, images, volumes, and networks with a modern, responsive TUI.

✨ Features

• Container Management - View, start, stop, restart, and manage containers
• Image Management - Browse, pull, remove, and inspect Docker images
• Volume Management - Manage Docker volumes and their data
• Network Management - Configure and manage Docker networks
• Real-time Search & Filtering - Quick search across all views with / key
• Real-time Monitoring - Live updates of container status and resource usage
• Theme Support - Customizable color schemes and UI appearance
• Column Configuration - Customize table columns with: responsive widths, alignment, and visibility
• Remote Host Support - Connect to remote Docker hosts via SSH
• Log Viewing - Real-time container logs with search and filtering

🚀 Quick Start

Prerequisites

• Docker Desktop or Docker Engine - Download Docker
• Cross-platform support: Windows, Linux, macOS

Note: You only need Go 1.25.0+ if you want to build from source. Pre-built binaries do not require Go to be installed.

Installation

For detailed installation instructions, visit our Installation Guide.

Quick commands:

# Clone and build
git clone https://github.com/wikczerski/whaletui.git
cd whaletui
go build -o whaletui

# Run
./whaletui

Pre-built binaries: Available on the Releases page.

Usage

Basic Commands

1. Launch whaletui - Run ./whaletui (or whaletui.exe on Windows)

2. Navigate the Interface - Use arrow keys, Tab, and Enter to navigate

3. Container Operations - Select containers and use keyboard shortcuts for actions

4. Search & Filter - Press / to search and filter items across all views

Search & Filtering

WhaleTUI includes powerful search functionality:

• Quick Search: Press / to enter search mode
• Real-time Filtering: Search updates as you type
• Cross-column Search: Search across all visible columns
• Search Persistence: Press Enter to keep search active
• Search Restoration: Press / again to restore previous search
• Clear Search: Press ESC to clear and return to full view

Remote Host Connection

whaletui supports connecting to remote Docker hosts using the connect subcommand:

# Basic SSH connection
./whaletui connect --host 192.168.1.100 --user admin

# With custom port
./whaletui connect --host 192.168.1.100 --user admin --port 2376

# With additional options
./whaletui connect --host 192.168.1.100 --user admin --refresh 10 --log-level DEBUG

# Using TCP protocol
./whaletui connect --host tcp://192.168.1.100 --user admin

# With port in host string
./whaletui connect --host 192.168.1.100:2375 --user admin

Command Line Options

• whaletui - Start with local Docker instance (default)
• whaletui connect - Connect to a remote Docker host via SSH
• whaletui theme - Manage theme configuration
• whaletui --help - Show help and available options

🎨 Theme Configuration

whaletui supports multiple theme formats for customizing the UI appearance:

JSON Theme Example:

{
  "colors": {
    "primary": "#00ff00",
    "secondary": "#ff00ff",
    "background": "#000000",
    "text": "#ffffff"
  }
}

YAML Theme Example:

colors:
  primary: "#00ff00"
  secondary: "#ff00ff"
  background: "#000000"
  text: "#ffffff"

Apply a theme:

whaletui --theme config/custom-theme.yaml
whaletui --theme config/theme.json

📊 Column Configuration

Customize table columns with responsive widths, alignment, and visibility controls:

YAML Configuration Example:

tableLimits:
  views:
    containers:
      columns:
        name:
          width_percent: 40
          min_width: 20
          max_width: 60
          alignment: "left"
          display_name: "Container Name"
        status:
          width_percent: 20
          alignment: "right"
        ports:
          width_percent: 25
          visible: true

Key Features:

• Percentage-based widths with min/max constraints
• Per-view configurations for different data types
• Column visibility control to show/hide specific columns
• Custom alignment (left, right, center) for better readability
• Display name customization for column headers

For detailed configuration options, see our Column Configuration Guide and Configuration Examples.

📚 Documentation

• Installation Guide - Setup and installation instructions
• Quick Start Guide - Get up and running quickly
• Column Configuration - Customize table columns and layouts
• Configuration Examples - Practical configuration examples
• Docker Concepts - Learn about Docker management with WhaleTUI

🏗️ Architecture

whaletui follows a modular architecture with clear separation of concerns:

whaletui/
├── cmd/           # Command line interface
├── internal/      # Internal application logic
│   ├── app/       # Application core
│   ├── config/    # Configuration management
│   ├── docker/    # Docker client operations
│   ├── services/  # Business logic services
│   └── ui/        # Terminal UI components
├── config/        # Configuration files
└── docs/          # Documentation

🛠️ Development

Building from Source

# Basic build
go build -o whaletui

# Cross-platform builds
GOOS=windows GOARCH=amd64 go build -o whaletui.exe
GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o whaletui

Running Tests

go test ./...

Local Development

# Run locally
./whaletui

# Connect to remote host for testing
./whaletui connect --host 192.168.1.100 --user admin

# Run with debug logging
./whaletui --log-level DEBUG

# Run with custom refresh rate
./whaletui --refresh 10

# Full remote connection with options
./whaletui connect --host 192.168.1.100 --user admin --port 2376 --refresh 10 --log-level DEBUG

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

Acknowledgments

• Inspired by k9s for Kubernetes management
• Built with tview for the terminal UI
• Uses tcell for terminal handling