Metadata-Version: 2.3
Name: wandb-tui
Version: 0.1.0
Summary: Terminal dashboard for comparing Weights & Biases runs from project or run URLs
Keywords: wandb,weights-and-biases,tui,mlops,plotext
Author: Sam Foreman
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: requests>=2.31
Requires-Dist: plotext>=5.3
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/saforem2/wandb-tui
Project-URL: Issues, https://github.com/saforem2/wandb-tui/issues
Project-URL: Repository, https://github.com/saforem2/wandb-tui
Description-Content-Type: text/markdown

# wandb-tui

A lightweight terminal dashboard for comparing Weights & Biases runs directly from W&B project or run URLs.

It was built for remote/cloud W&B runs when you want a LEET-like terminal view without needing the original local `wandb/` run directories.

## Features

- Single-run metric dashboard
- Multi-run project comparison from a W&B project URL
- W&B-style per-run colored columns
- `plotext` line charts for multi-run metric overlays
- Metric search, group filtering, sorting, and refresh
- JSON export for downstream analysis
- Works against public runs without `wandb` installed; uses `WANDB_API_KEY` automatically for private runs

## Install / run with uv

```bash
uv sync
```

Run the CLI entrypoint:

```bash
uv run wandb-tui --help
```

Or run it as a Python module:

```bash
uv run python -m wandb_tui --help
```

## Usage

### Compare recent runs in a project

```bash
uv run wandb-tui \
  'https://wandb.ai/aurora_gpt/ezpz.examples.fsdp_tp?nw=nwuserforemans' \
  --runs 8
```

Press `m` to toggle from table mode to plot mode.

### View a single run

```bash
uv run wandb-tui \
  https://wandb.ai/aurora_gpt/ezpz.examples.fsdp_tp/runs/vrxuo55p
```

### Non-interactive table snapshot

```bash
uv run wandb-tui \
  'https://wandb.ai/aurora_gpt/ezpz.examples.fsdp_tp?nw=nwuserforemans' \
  --runs 8 \
  --once \
  --search train/loss \
  --group train
```

### Export JSON

```bash
uv run wandb-tui \
  'https://wandb.ai/aurora_gpt/ezpz.examples.fsdp_tp?nw=nwuserforemans' \
  --runs 8 \
  --json /tmp/wandb_project_metrics.json
```

## Controls

| Key | Action |
| --- | --- |
| `q` | Quit |
| `↑` / `↓`, `j` / `k` | Scroll |
| `PgUp` / `PgDn` | Page scroll |
| `Home` / `End` | Jump |
| `/` | Search metric names |
| `Esc` | Clear search |
| `g` | Cycle metric group filter |
| `m` | Toggle table/chart mode in project view |
| `s` | Cycle sort mode |
| `r` | Refresh from W&B |
| `?` | Help |

## W&B LEET comparison

W&B's official LEET TUI is excellent for local `wandb/` directories and `.wandb` files, and newer versions support remote single-run URLs. This tool focuses on remote multi-run project comparisons over W&B's GraphQL API.

## Notes

- Public W&B projects/runs can be queried without authentication.
- For private projects, set `WANDB_API_KEY` in your environment.
- `plotext` is included as a dependency for chart mode.
