Databricks Setup-Local

REQUIRED FIRST: Use databricks-core for CLI, authentication, and profile selection. Never use a default profile. For an existing environment, use databricks-execution-compute.

Workflow

1. Check CLI and authentication

databricks version                         # must be >= v1.12.0
databricks auth describe --profile <PROFILE>

Prefer the latest stable CLI; no online lookup is required. Compare the full semantic version: v0.299.1 is older than v1.12.0. If missing or older, or setup-local is absent from help, reports unknown command, or rejects a documented flag, stop. Use databricks-core to upgrade with approval and verify; never recreate setup-local manually.

Use the selected profile for every workspace command. Do not convert another package manager without approval.

2. Confirm the project directory

Confirm the root containing (or intended to contain) pyproject.toml, .venv, and uv.lock; ask if multiple roots are plausible. Use it for preview and apply. It must be greenfield or uv-managed, but need not be writable for preview.

3. Select one target

Choose exactly one branch:

• Cluster: use --cluster-id <ID> or --cluster-name <NAME>. If unknown, list clusters with the selected profile and ask; see examples.
• Serverless: use --serverless-version <N>. No version-list command exists; ask if unspecified.
• Job task: use --job-task <JOB_ID>.<TASK_KEY>. If the task is unknown, run databricks jobs get <JOB_ID> --profile <PROFILE> --output json, present task keys, and ask.
• Bundle: a project with databricks.yml. Use databricks-dabs to inspect its root and selected target. Omit compute flags only when that target resolves supported classic or serverless compute; otherwise ask. Add --target <BUNDLE_TARGET> for a named target.

Never combine compute flags. If no branch resolves, ask the user.

4. Preview

Dry-run first; it writes and installs nothing:

databricks environments setup-local --profile <PROFILE> <TARGET_ARGS> --dry-run --output json

For bundles, <TARGET_ARGS> is empty or --target <BUNDLE_TARGET>. Default to normal mode. Use --constraints-only only when the user explicitly does not want this command managing databricks-connect. See JSON output and examples.

5. Obtain approval and apply

Before apply, verify the directory is writable and run uv --version. Ask before installing uv; never silently set DATABRICKS_LOCALENV_AUTO_INSTALL_UV=1 or run a remote installer.

Show the target, versions, warnings, plan.diff, and directory. Explain that apply may:

• back up and rewrite pyproject.toml;
• install Python and dependencies;
• update .venv and uv.lock.

For --serverless-version N in a bundle, also disclose the post-apply job YAML synchronization described below so approval covers both mutations.

Apply only after the user requested provisioning or approves that plan for the named directory. Preserve the directory, profile, target, and mode.

If the directory, profile, target, mode, or project files change after preview, rerun --dry-run, show the new plan, and obtain approval again. Treat its resolved Python, databricks-connect, and managed constraints as authoritative; do not substitute guessed versions. Reconcile user-owned dependency conflicts separately, with approval.

6. Handle the result

• ok: true: for --serverless-version N in a bundle, update every existing job environments[].spec.environment_version in its YAML sources to "N", then validate the bundle. Report if none exist; do not invent one. Skip this for cluster and job-task targets. Report target, versions, warnings, and venvPath; prefer uv run <cmd> or derive the platform-specific interpreter from venvPath.
• ok: false: use troubleshooting. Ask before diagnostic runs that mutate files and before filing an external issue.
• No JSON: inspect stderr for a pre-pipeline CLI, authentication, directory, or cache error.