Metadata-Version: 2.4
Name: dbt-docket
Version: 0.1.2
Summary: A GUI viewer for dbt runs
Author-email: Your Name <you@example.com>
License: MIT
Keywords: dag,data,dbt,gui
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: fastapi>=0.100
Requires-Dist: httpx>=0.24
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.23
Requires-Dist: websockets>=11.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install dbt-docket
```

Or install from source:

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

## Quick Start

From your dbt project directory:

```bash
# 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):

```yaml
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:

```bash
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

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

## License

MIT
