Setup

ADE-Bench Setup

The plugin generates task definitions. ade-bench (a separate Python project) is what actually executes them inside Docker against the user's data. This skill makes ade-bench available so generated tasks can be run.

Default install location: ~/.ade-bench. The skill git clones ade-bench there, runs uv sync to install Python deps, and uv tool install . to put the ade CLI on PATH.

Step 1: Parse Arguments

• --path <install-path>: Where to install ade-bench. Default: ~/.ade-bench.

Resolve ~ to the user's home directory. Use the resolved absolute path in every step below.

Step 2: Check Prerequisites

Run these in parallel and collect the results:

1. git: command -v git
2. uv: command -v uv
3. docker: command -v docker

If any of the three is missing, stop and tell the user what's missing and how to install it:

• git: Use the system package manager (brew install git, apt install git, etc.).
• uv: curl -LsSf https://astral.sh/uv/install.sh | sh (then restart the shell or source ~/.zshrc).
• docker: Recommend Docker Desktop, Colima, or OrbStack. Don't try to install or start Docker. The user must do this.

If docker is installed but not running, that's fine for setup — flag it but proceed. Docker only needs to be running when tasks actually execute.

Step 3: Detect Existing Installation

Two checks, in order:

1. Already installed via this skill?

   test -f <install-path>/pyproject.toml && grep -q 'name = "ade-bench"' <install-path>/pyproject.toml
   

2. Already on PATH from somewhere else?

   command -v ade
   

If either succeeds:

• Run ade --help to confirm the CLI works.
• Tell the user where ade-bench was found and that no install is needed.
• Skip to Step 7 (DuckDB database download — still verify it's been done) and continue from there.

If <install-path> exists but is not a valid ade-bench checkout (different repo, partial clone, leftover files), stop and ask the user whether to remove and reinstall or pick a different path. Do not silently overwrite.

If nothing is installed, proceed to Step 4.

Step 4: Clone the Repository

git clone https://github.com/dbt-labs/ade-bench.git <install-path>

If the clone fails, report the error verbatim and stop. The most common reasons are no network, GitHub auth issues, or <install-path> already existing as a non-empty directory.

Step 5: Install Python Dependencies

cd <install-path> && uv sync

This builds a local virtualenv at <install-path>/.venv and installs all Python deps. Expect this to take 30 seconds to a couple of minutes depending on network speed.

Step 6: Install the ade CLI Globally

cd <install-path> && uv tool install .

uv tool install puts the ade entry point on the user's PATH (under ~/.local/bin by default). After this, ade run … works from any directory.

Verify:

command -v ade && ade --help

If ade is not found after uv tool install, the user's ~/.local/bin is probably not on PATH. Tell them:

"ade was installed but isn't on PATH. Add ~/.local/bin to your PATH — for zsh, run: echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc && source ~/.zshrc"

Don't modify the user's shell config yourself.

Step 7: Download Bundled DuckDB Databases

ade-bench ships several bundled dbt projects (airbnb, f1, quickbooks, …) along with reference DuckDB files used as the source database for those projects. The .duckdb files live in a GitHub release (dbt-labs/ade-bench:databases), not in the repo itself — <install-path>/shared/databases/duckdb/ is empty after git clone. Without these files, any task targeting a bundled project fails at setup_duckdb with "DuckDB database '' not found at ".

The release currently totals ~225 MB. Skip this step only if the user has explicitly said they'll exclusively use their own dbt projects with their own DuckDB files (the generators write db_dir into task.yaml for those — bundled databases aren't consulted).

7.1 Check if already populated

Compare the number of .duckdb files locally present against the expected count from the GitHub release. Skip the download only when they match exactly — a partial state (e.g., 10 of 11 files) should fall through to Step 7.2 so gh release download can fetch the missing file(s).

present=$(ls <install-path>/shared/databases/duckdb/*.duckdb 2>/dev/null | wc -l | tr -d ' ')

if [ "$present" -gt 0 ]; then
  expected=$(gh release view databases --repo dbt-labs/ade-bench \
    --json assets \
    --jq '[.assets[] | select(.name | endswith(".duckdb"))] | length' 2>/dev/null)

  if [ -n "$expected" ] && [ "$present" -eq "$expected" ]; then
    # All files present — skip the rest of Step 7 and report "databases already present"
    :
  fi
fi

Notes:

• Costs one extra gh release view API call only when some files are already present, so the first-run path is unaffected.
• If gh isn't installed or isn't authenticated, the expected lookup returns empty and the check falls through to Step 7.2 (which has its own gh-missing branch with manual-download instructions). Consistent.
• This makes the check survive future ade-bench bundled-project additions without touching the skill — the threshold is whatever the release says it is.

Stash the expected value if you got one — Step 7.4 uses it for the user-facing report.

7.2 Check gh availability and auth

command -v gh && gh auth status

• gh missing → tell the user to either install it (brew install gh) or download the release assets manually from https://github.com/dbt-labs/ade-bench/releases/tag/databases into <install-path>/shared/databases/duckdb/. Skip the download and continue to Step 8.
• gh present but not authenticated → tell the user to run gh auth login and re-invoke /ade-bench:setup. Skip the download and continue to Step 8.

7.3 Download

gh release download databases \
  --repo dbt-labs/ade-bench \
  --pattern "*.duckdb" \
  --dir <install-path>/shared/databases/duckdb

If the command fails partway through (network, auth expiry), report the error verbatim and continue. The user can rerun the same command later — gh release download skips files that already exist.

Do not block the rest of setup on a download failure. Snowflake-only users don't need these, and a partial download can be completed manually later.

7.4 Verify

present=$(ls <install-path>/shared/databases/duckdb/*.duckdb 2>/dev/null | wc -l | tr -d ' ')
size=$(du -sh <install-path>/shared/databases/duckdb 2>/dev/null | cut -f1)

Use the expected value from Step 7.1 if you have it. Report the count as <present>/<expected> so a partial state is visually obvious — e.g.:

• All present: DuckDB DBs: 11/11 files (224 MB)
• Partial: DuckDB DBs: 10/11 files (210 MB) — re-run /ade-bench:setup to fetch the missing file
• Expected-count unknown (gh missing/unauthed): DuckDB DBs: 11 files (224 MB) — fall back to just the count.

Step 8: Verify Docker

docker ps

If it fails:

• "Cannot connect to the Docker daemon" → Docker isn't running. Tell the user to start it.
• "command not found" → Already handled in Step 2.

If Docker isn't running, that's fine for now — flag it but don't block. The user only needs it when running tasks.

Step 9: Initialize Snowflake .env (Conditional)

Only if the user has indicated they'll be running Snowflake-targeted tasks (or if the calling skill detected a Snowflake project). Skip for DuckDB-only users.

test -f <install-path>/.env || cp <install-path>/.env.example <install-path>/.env

Tell the user:

"I copied .env.example to .env at <install-path>/.env. Open it and fill in your Snowflake credentials before running Snowflake tasks. Required vars: SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER, SNOWFLAKE_PASSWORD, SNOWFLAKE_ROLE, SNOWFLAKE_WAREHOUSE."

Do not prompt for credentials. Do not write credential values to any file. The user fills in .env themselves.

Step 10: Report Results

Summarize for the user:

ade-bench setup complete.
  Install path:    <install-path>
  CLI on PATH:     ade (verified with `ade --help`)
  DuckDB DBs:      <present>/<expected> files (<size>) | <present> files (<size>) if expected unknown | not downloaded — install `gh` and rerun, or download manually
  Docker:          <running | installed but not running | not installed>
  Snowflake env:   <.env created at <path>, fill in credentials | not initialized — DuckDB-only>

Next: run `/ade-bench:plan-tasks <project-path>` or `/ade-bench:create-task <project-path>` to generate your first benchmark tasks.

Important Guidelines

• Don't install dependencies the user already has. Step 3 short-circuits if a working ade-bench is already on the system.
• Don't write credentials anywhere. The Snowflake setup ends at copying .env.example to .env. The user fills it in.
• Don't start Docker. If Docker isn't running, tell the user. Don't run open -a Docker or anything similar — it's surprising and sometimes wrong.
• Don't modify the user's shell config. If PATH adjustment is needed, tell the user the command to run; don't run it.
• Default install location is ~/.ade-bench. Honor --path if provided, but don't invent alternative defaults.