docker-orb 1.0.0

Interactive terminal UI for streaming and filtering Docker Compose container logs across multiple services

docker-orb

Watching logs across a multi-container Compose stack usually means juggling multiple docker compose logs windows and grepping after the fact, or writing complex regex just to add a couple of filters. docker-orb streams logs from every container in your selected services into one merged, colorized view — and lets you filter, highlight, and search while it's streaming.

Built with Textual, docker-orb is a full terminal UI: an interactive setup wizard walks you through picking a project, services, and filter patterns — no flags required — or skip straight to the viewer with CLI arguments if you prefer. Save named session configs to reload your exact setup later; passively collect rare events in a monitor panel without losing your scroll position; get alerted when containers restart or go unhealthy; and add or remove services from the live stream without restarting.

Features

• Multi-container live tail — stream logs from any number of containers/services at once, each with a distinct color.
• Filters — hide lines matching a pattern, live-editable mid-session.
• Highlights — emphasize lines matching a pattern without hiding anything else.
• Monitors — passively collect matching lines into a separate panel so you can watch for rare events (e.g. job failed) without losing your scroll position in the main stream.
• Live search — search the whole buffered session, jump to a result, and keep streaming.
• Container health panel — flags containers that aren't Running or have crossed a restart threshold; restart a container or recreate a service from inside the app.
• Dump mode — fetch existing logs once (with --tail/--since) and exit, for scripting or one-off inspection, instead of a live stream.
• Saved configs — save a named combination of project, services, and patterns, and reload it later by name.
• JSON log formatting — auto-detects structured JSON log lines and shows time LEVEL message key=value ... instead of a raw JSON blob, with a toggle back to raw and a detail view (Enter on a clicked line) for the full pretty-printed object.
• Collapse repeated lines — journalctl-style: consecutive identical lines from the same container fold into a single "last line repeated N times" marker, toggleable, so a crash-looping container doesn't flood the stream.

Installation

Requires Python 3.10+, and docker with the Compose v2 plugin on your PATH (i.e. docker compose works). docker-orb shells out to your existing docker CLI and inherits its context/auth — no separate credentials or Docker SDK involved.

# Recommended — pipx keeps CLI tools in isolated environments. Not on PyPI
# yet, so install straight from GitHub:
pipx install git+https://github.com/adlidev/docker-orb

# Or with plain pip, inside your own venv:
git clone https://github.com/adlidev/docker-orb.git
cd docker-orb
pip install -e .

This installs two commands: docker-orb and docker-orb-inject (a small test utility for injecting fake log lines into a running container — see the User Guide).

For development / contributing:

git clone https://github.com/adlidev/docker-orb.git
cd docker-orb
pip install -e . --group dev

Quick start

# No arguments — launches the interactive setup wizard
docker-orb

# Skip the wizard: watch two services live
docker-orb -n myapp -p api -p worker

# Watch every service in a project
docker-orb -n myapp --all-containers

# One-shot dump instead of a live stream
docker-orb -n myapp --dump --tail 500

# Pre-filter/highlight from the command line
docker-orb -n myapp -p worker -f DEBUG -H ERROR --health

-n/--project takes the Compose project name (what docker compose -p expects — usually the directory name your docker-compose.yml lives in, unless overridden by a top-level name: key or COMPOSE_PROJECT_NAME). If omitted, docker-orb resolves it the same way docker compose does for the current directory.

Once you're in the viewer, press F / H / M to edit filters, highlights, or monitors live, / to search, P to add/remove streamed services, and Space to pause. See the User Guide for the full keybinding reference and pattern syntax.

Development

pip install -e . --group dev
pytest                    # run the test suite
textual run --dev src/docker_orb/__main__.py   # live-reload dev mode

A local Compose stack with 8 fake log-generating services is included for manual testing:

cd infra
make up
docker-orb -n logviewer-demo --all-containers --health

See infra/README.md for the service list and good filter/monitor test patterns, and CLAUDE.md for architecture notes.

Relationship to kube-orb

docker-orb is a sibling project to kube-orb, Adli's Kubernetes-flavored log viewer. They share a UI architecture (Textual viewer, wizard, filters/highlights/monitors, JSON formatting) but each talks to its own backend directly — docker-orb shells out to docker/docker compose, kube-orb shells out to kubectl — and they're maintained as independent tools rather than one project trying to do both.

License

MIT License