sleepybricks

sleepybricks is a succinct Typer-based CLI that wraps the databricks SDK to run operations across multiple workspaces at once.

It authenticates by reading profiles from ~/.databrickscfg (the same file the databricks CLI uses) and gives a graceful error when that file or a requested profile is missing.

Authentication

Most commands take a comma-separated profile_list (e.g. dev,stg,us) naming profiles defined in ~/.databrickscfg (groups-audit is the exception — it's account-scoped). Create that file with the databricks CLI if you don't have one:

databricks configure --token   # repeat once per workspace/profile

Install

Install the CLI globally with uv:

uv tool install sleepybricks

It's recommended to set an alias in your shell config:

alias bricks='sleepybricks'

Commands

Most commands accept --json to emit structured output instead of a table (handy for pipelines). (snippets prints reference text, so it has no --json.)

sleepybricks dash-links "Scheduled Triage Device Metrics" "dev,eu"
sleepybricks sql -s "select * from my_tbl" "dev,stg,us"
sleepybricks sql -s "select revenue from sales" "dev,stg" --sum revenue
sleepybricks sql -f "./query.sql" "dev,stg" --out ./results   # writes ./results.csv
export SLEEPYBRICKS_SECRET_STAGE='s3cret'
sleepybricks write-secret my_scope.api_key "dev,stg"
sleepybricks pull-repo databricks_templates "dev,stg,us"
sleepybricks run-job "Nightly ETL" "dev,stg"
sleepybricks update-clusters "dev,stg,us"
sleepybricks put-file ./setup.py /Users/me@co.com/setup.py "dev,stg"
sleepybricks propagate-file dev /Users/me@co.com/my_notebook "qa,stg"
sleepybricks create-workspace-folder databricks_templates "dev,stg,us"
sleepybricks snippets paths
sleepybricks snippets workspaces
sleepybricks groups-audit --inactive
sleepybricks --help

Dashboard names are matched case-sensitively and are not unique in databricks; the first match per workspace is used and a warning is shown when duplicates exist. run-job also matches job names case-sensitively, but because job names are not unique it will not run anything in a workspace where more than one job shares the exact name — it reports the count instead. The sql command needs a serverless SQL warehouse in each workspace — see Configuration below.

sql options

• --out <path> — write all workspaces' rows to one CSV (with a leading profile column). The .csv extension is enforced: a path without it, or with a different one, gets .csv appended (results → results.csv, out.txt → out.txt.csv).
• --sum <column> — instead of printing rows, sum that column per workspace and show a grand total across all workspaces.
• --out and --sum are mutually exclusive.

write-secret and secrets

The secret value is not a command-line argument (that would leak it into shell history and ps). Instead, export it into SLEEPYBRICKS_SECRET_STAGE first; write-secret reads it from there.

Configuration

sleepybricks is a sleepy util and reads its settings from the shared ~/sleepyconfig/params.yml. Each sleepy util owns only its own <tool>_<name> keys; sleepybricks uses the bricks_ prefix. If the file is absent, sleepybricks writes only its own section below and prints a note. If a value it needs is missing, it prints this snippet and asks you to verify your config. Keys:

• bricks_table_style — tabulate table style used for all output (e.g. simple, rounded_grid, github).
• bricks_serverless_warehouse_name — name of the serverless SQL warehouse used for compute. The <env> token is replaced with the active profile name, so the default <env>_serverless_warehouse resolves to dev_serverless_warehouse for the dev profile. Use a static value (no token) if your warehouse name is the same everywhere.
• bricks_env_emojis — per-profile emoji used to decorate output labels.
• bricks_display_names — per-profile friendly name used in output labels.
• bricks_personal_cluster_name — cluster name that update-clusters ensures exists.
• bricks_personal_cluster_policy — cluster policy name applied by update-clusters (must already exist in the workspace).

# sleepybricks
bricks_table_style: simple
bricks_serverless_warehouse_name: <env>_serverless_warehouse
bricks_env_emojis:
  dev: "👩‍💻"
  stg: "🔧"
  us: "🇺🇸"
bricks_display_names:
  dev: "Development"
  stg: "Staging"
  us: "United States"
bricks_personal_cluster_name: personal_cluster
bricks_personal_cluster_policy: "Personal Compute"

Development

Create the environment and install in editable mode with uv:

uv venv
uv pip install -e ".[dev]"

Then run uv run pytest, or ./tools/test.sh. Tests use fakes for the databricks client and never touch a real workspace. Tear down with rm -rf .venv.

Documentation

• Specification — what the tool does
• Project outline — repository layout
• Test drive — setup, testing, and CLI usage
• Adding a command — how to extend the CLI
• Publishing — release to PyPI