dockviz-cli

README

dockviz-cli

A real-time Docker environment dashboard for your terminal.

한국어 문서 (Korean)

---

dockviz-cli is an interactive terminal UI (TUI) that gives you a live view of your Docker environment — containers, resource usage, networks, and images — without leaving the terminal.

Run dockviz --demo to try it right now without Docker.

Features

• Real-time stats — CPU and memory usage refreshed every 2 seconds with fixed-scale sparklines (▁▂▃▄▅▆▇█)
• Failure propagation visualizer — Networks tab split view: coloured topology (● running / ◑ restarting / ✗ dead) on the left, per-network event timeline with exit codes and OOM annotations on the right
• Event timeline — live Docker lifecycle events (create / start / die / restart / destroy) with exit code and OOM kill detection
• Image browser — one row per tag, alphabetically sorted, safe tag-by-tag deletion with multi-tag warning
• Container control — start / stop / delete containers with a single key press and confirmation overlay
• Real-time log streaming — l key opens a scrollable live log view with ERROR/WARN color coding
• Image pull progress — dockviz pull <image> shows per-layer download bars
• Detail view — per-container info (ID, image, ports, status)
• Demo mode — --demo flag runs with simulated data, no Docker required
• Remote host — --host tcp://host:2375 or DOCKER_HOST env var to connect to a remote daemon

Installation

Linux / macOS — one-liner (auto-detects OS and architecture)

curl -sL "https://github.com/0206pdh/dockviz-cli/releases/latest/download/dockviz-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')" \
  -o /usr/local/bin/dockviz && chmod +x /usr/local/bin/dockviz

Works on Linux (amd64/arm64) and macOS (Intel/Apple Silicon) without any modification.

To update to the latest version, run the same command again.

Manual download (pick your platform)

# Linux amd64 (most servers/VMs)
curl -sL https://github.com/0206pdh/dockviz-cli/releases/latest/download/dockviz-linux-amd64 \
  -o /usr/local/bin/dockviz && chmod +x /usr/local/bin/dockviz

# Linux arm64 (Raspberry Pi, AWS Graviton, etc.)
curl -sL https://github.com/0206pdh/dockviz-cli/releases/latest/download/dockviz-linux-arm64 \
  -o /usr/local/bin/dockviz && chmod +x /usr/local/bin/dockviz

# macOS Intel
curl -sL https://github.com/0206pdh/dockviz-cli/releases/latest/download/dockviz-darwin-amd64 \
  -o /usr/local/bin/dockviz && chmod +x /usr/local/bin/dockviz

# macOS Apple Silicon (M1/M2/M3)
curl -sL https://github.com/0206pdh/dockviz-cli/releases/latest/download/dockviz-darwin-arm64 \
  -o /usr/local/bin/dockviz && chmod +x /usr/local/bin/dockviz

Windows

Download from the Releases page:

• dockviz-windows-amd64.exe — Intel/AMD
• dockviz-windows-arm64.exe — ARM (Surface Pro X, etc.)

Build from source

git clone https://github.com/0206pdh/dockviz-cli.git
cd dockviz-cli
go build -o dockviz .

go install

go install github.com/0206pdh/dockviz-cli@latest

Quick Start

Prerequisites

• Docker Engine running (not required for --demo)

Run

# Connect to your local Docker daemon
dockviz

# Preview with simulated data — no Docker required
dockviz --demo

# Connect to a remote Docker daemon
dockviz --host tcp://192.168.1.100:2375

# Or use the standard Docker environment variable
DOCKER_HOST=tcp://192.168.1.100:2375 dockviz

# Pull an image with live layer progress
dockviz pull nginx:alpine

Keyboard Shortcuts

Key	Action
q / Ctrl+C	Quit
Tab	Switch panel (Containers → Networks → Images → Events)
↑ / k	Move up
↓ / j	Move down
Enter	Open container detail
Esc	Go back
s	Start / Stop selected container
d	Delete selected container or image tag (with confirmation)
l	Open live log stream
r	Force refresh / reconnect event stream if disconnected
g	Open full-screen CPU/MEM history chart for selected container

Architecture

This project follows The Elm Architecture (TEA) as implemented by Bubble Tea:

main.go
  └── cmd.Execute()          ← Cobra CLI (--demo flag)
        └── tui.Start()
              ├── docker.NewClient()      ← Docker SDK / DemoClient
              └── tea.NewProgram(model)   ← Bubble Tea event loop
                    ├── Init()   → first data fetch + ticker
                    ├── Update() → key events, ticks, Docker responses
                    └── View()   → Lip Gloss styled terminal output

Package layout

dockviz-cli/
├── main.go                        # entry point
├── cmd/
│   ├── root.go                    # Cobra CLI, --demo flag
│   └── pull.go                    # `dockviz pull <image>` subcommand
└── internal/
    ├── docker/
    │   ├── interface.go           # DockerClient interface
    │   ├── client.go              # live Docker SDK wrapper
    │   ├── demo.go                # animated demo data (no daemon needed)
    │   ├── containers.go          # list, stats, start/stop/restart/delete
    │   ├── networks.go            # network topology (NetworkInspect per network)
    │   ├── images.go              # image list (one row per tag, sorted)
    │   ├── state.go               # ContainerState — health derived from event stream
    │   ├── events.go              # lifecycle event streaming (ExitCode, OOMKilled)
    │   ├── pull.go                # image pull with per-layer progress stream
    │   └── logs.go                # container log streaming (stdcopy demux)
    ├── tui/
    │   ├── model.go               # state (TEA Model) — ContainerStates map
    │   ├── update.go              # event handling (TEA Update) — state transitions
    │   ├── view.go                # rendering (TEA View) — split Networks layout
    │   ├── keymap.go              # keyboard bindings
    │   ├── pull.go                # pull progress TUI program
    │   └── start.go               # wires docker client → TUI
    └── ui/
        ├── styles.go              # Lip Gloss color palette, styles, sparkline
        └── graph.go               # topology graph with health-coloured nodes

Tech Stack

Layer	Library	Purpose
TUI framework	Bubble Tea	Event loop, TEA pattern
TUI styling	Lip Gloss	Colors, borders, layout
TUI components	Bubbles	Spinner, key bindings
Docker API	Docker SDK for Go	Container / network / image data
CLI	Cobra	Flags and subcommands

Roadmap

• Project scaffold and build pipeline
• Docker client wrapper with interface (live + demo mode)
• Container list panel with live CPU/MEM stats (parallel fetch)
• CPU sparkline — fixed 0-100% scale, 10-point unicode bar per container
• Network topology graph with health-coloured nodes (● ◑ ✗ ○)
• Networks tab split layout — topology left, per-network event timeline right
• Container lifecycle event streaming with exit code and OOM kill detection
• ContainerState tracking — failure propagation across network topology
• Image browser — one row per tag, alphabetical order, tag-by-tag safe delete
• Container detail view
• --demo mode (no Docker required)
• dockviz pull <image> — real-time per-layer download progress
• Container / image delete with confirmation overlay (d key)
• Real-time log streaming with color coding (l key)
• Event stream disconnect detection + r to reconnect
• GitHub Actions release pipeline (Linux / Windows / macOS binaries on tag push)
• Remote Docker host support (--host flag + DOCKER_HOST env var)
• Container stats history chart — full-screen CPU/MEM bar chart per container (g key)

License

MIT © 2026 0206pdh