bricktop

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

pipx install bricktop          # recommended
uv tool install bricktop       # alternative

Or run without installing:

uvx bricktop

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

Quick start

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:

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:

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

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.