Metadata-Version: 2.4
Name: bricktop
Version: 0.1.0
Summary: Textual TUI system monitor for Databricks
Project-URL: Homepage, https://github.com/rattle99/bricktop
Project-URL: Repository, https://github.com/rattle99/bricktop
Project-URL: Issues, https://github.com/rattle99/bricktop/issues
Author-email: rattle99 <rattle99@users.noreply.github.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: cli,dashboard,databricks,monitor,observability,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: databricks-sdk>=0.30
Requires-Dist: textual>=0.80
Description-Content-Type: text/markdown

# bricktop

[![PyPI](https://img.shields.io/pypi/v/bricktop?style=for-the-badge&logo=pypi&logoColor=white&color=FF3621)](https://pypi.org/project/bricktop/)
[![Python](https://img.shields.io/pypi/pyversions/bricktop?style=for-the-badge&logo=python&logoColor=white&color=FF3621)](https://pypi.org/project/bricktop/)
[![License](https://img.shields.io/badge/license-GPL--3.0-FF3621?style=for-the-badge)](LICENSE)

A Textual TUI system monitor for Databricks. Think `btop` or `k9s`, but for your Databricks workspace.

## Features

- Dashboard with longest-running clusters, active runs, and a merged activity feed.
- Clusters tab: every all-purpose cluster with state, uptime, workers, and idle time.
- Jobs tab: your submitted runs with state, duration, and cluster.
- Activity tab: live merged feed of cluster events and run state transitions.
- Interactive refresh control. Press `+` and `-` to tune the polling interval.
- Reads `~/.databrickscfg` transparently if you already use the Databricks CLI.

## Install

```sh
pipx install bricktop          # recommended
uv tool install bricktop       # alternative
```

Or run without installing:

```sh
uvx bricktop
```

Requires Python 3.11 or newer, a Databricks workspace, and a Personal Access Token. Linux and macOS only.

## Quick start

```sh
bricktop
```

On first launch a modal asks for your workspace URL (e.g.
`https://dbc-xxxxxxxx.cloud.databricks.com`) and a Personal Access Token.
Both are saved to `~/.config/bricktop/config.toml` with permission `600`.
If you already have `~/.databrickscfg` from the Databricks CLI, the modal
is skipped and the existing credentials are used.

To generate a Personal Access Token, open the Databricks UI and go to
**User Settings > Developer > Access tokens > Generate new token**.
Copy the token immediately; the UI will not show it again.

## Keys

| Key | Action |
|---|---|
| `?` | Help overlay |
| `f` | Freeze / unfreeze polling |
| `+` / `-` | Adjust refresh interval (2 to 60s) |
| `r` | Force refresh now |
| `t` | Cycle theme |
| `1` `2` `3` `4` | Jump to Dashboard, Clusters, Jobs, Activity |
| `q` | Quit |

## Files

| Path | Purpose |
|---|---|
| `~/.config/bricktop/config.toml` | Workspace URL, PAT, and UI preferences. chmod 600. |
| `~/.local/state/bricktop/bricktop.log` | Rotating log file (2 MB, 3 backups). |
| `~/.databrickscfg` | Read transparently if present; never written. |

All three paths honour their `XDG_*_HOME` env vars if set.

## Troubleshooting

When something looks wrong, run:

```sh
bricktop doctor
```

It prints the resolved paths, the credential source, and runs a
`current-user me` call to verify connectivity. Detailed traces of every
refresh tick land in `~/.local/state/bricktop/bricktop.log`.

If the Python SDK cannot reach your workspace (e.g. corporate network
policy routes by binary identity), bricktop falls back to the
`databricks` CLI automatically. A one-time toast notifies you and the
active transport appears in the header subtitle. To force a specific
transport, pass `--transport sdk` or `--transport cli`.

The fallback requires the official Databricks CLI on `PATH`:

```sh
brew tap databricks/tap && brew install databricks            # macOS
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sh   # Linux
```

See the [Databricks CLI install guide](https://docs.databricks.com/aws/en/dev-tools/cli/install)
for other methods.

## CLI reference

```
bricktop                                # launches TUI (auto-fallback by default)
bricktop configure                      # opens the config modal in a one-shot run
bricktop doctor                         # prints resolved paths and connectivity
bricktop --debug                        # enables debug logging
bricktop --reset-config                 # deletes config.toml and relaunches
bricktop --config /path/to/cfg.toml     # alternate bricktop config file
bricktop --databricks-cfg /path/to/cfg  # alternate ~/.databrickscfg path
bricktop --profile staging              # pick a non-DEFAULT profile
bricktop --transport sdk                # force the Python SDK transport
bricktop --transport cli                # force the databricks CLI transport
```

## Development

```sh
git clone https://github.com/rattle99/bricktop.git
cd bricktop
uv sync --dev
uv run pytest
uv run bricktop
```

## License

GPL-3.0-or-later. See [LICENSE](LICENSE).
