dbt-docket 0.1.0

A GUI viewer for dbt runs

dbt-docket

A real-time GUI for local dbt runs. Launch a web server that visualizes your DAG with color-coded model status, streams live logs, and lets you trigger new runs directly from the browser.

Installation

pip install dbt-docket

Or install from source:

git clone https://github.com/your-org/dbt-docket.git
cd dbt-docket
pip install -e ".[dev]"

Quick Start

From your dbt project directory:

# Run dbt with live visualization
dkt run -s stg_stripe_invoices+2

# Or just view the DAG without running
dkt view

# Custom port
dkt --port 9000 run -s model+

This starts a local web server and opens your browser. The GUI shows:

• Live DAG — Color-coded nodes (green = success, yellow = running, red = failed, gray = not started)
• Run stats — Progress bar, passed/failed/remaining counts
• Real-time logs — Streamed via WebSocket with level-based coloring
• Interactive graph — Zoom, pan, hover for tooltips, tap to center

Configuration

Create a docket.yml in your dbt project root (optional):

dbt_project_dir: .
profiles_dir: ~/.dbt

port: 8765
host: 127.0.0.1
open_browser: true

All settings have sensible defaults. You can also override via CLI flags:

dkt --port 9000 --host 0.0.0.0 run -s my_model

CLI Reference

dkt [options] <dbt-command> [dbt-options...]
dkt [options] view

Options:
  -c, --config PATH    Path to config file
  -p, --port PORT      Server port (default: 8765)
  -h, --host HOST      Server host (default: 127.0.0.1)
  --no-browser         Don't automatically open browser
  --help               Show help

Examples:
  dkt run -s stg_stripe_invoices+2
  dkt build --target prod
  dkt test -s my_model
  dkt view

How It Works

1. Parses your dbt manifest — Reads target/manifest.json to build the DAG (auto-compiles if missing)
2. Runs dbt with JSON logging — Spawns dbt --log-format json <your-args> as a subprocess
3. Parses output in real-time — Tracks model start/success/error events
4. Broadcasts via WebSocket — Pushes DAG updates, run state, and logs to the browser
5. Renders with Cytoscape.js — DAG layout using dagre, styled by execution status

Requirements

• Python 3.9+
• dbt installed and configured
• A dbt project with dbt_project.yml and compiled manifest

Development

pip install -e ".[dev]"
ruff check src
pytest

License

MIT