environments: clearer setup-local --help and output (DECO-27977)

acceptance/localenv/bundle-multiple-defaults/output.txt

@@ -1,7 +1,5 @@
-preflight  ok  uv [UV_VERSION]
-resolve    error  No compute target is selected. Select a cluster or serverless target, or pass --cluster-id / --cluster-name / --serverless-version / --job-task
-fetch      pending
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed while resolving your compute target.
+
+  No compute target is selected. Select a cluster or serverless target, or pass --cluster-id / --cluster-name / --serverless-version / --job-task
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/cluster-name-ambiguous/output.txt

@@ -1,7 +1,5 @@
-preflight  ok  check
-resolve    error  resolving cluster name "dup": there are 2 active clusters named "dup"; use --cluster-id to disambiguate
-fetch      pending
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed while resolving your compute target.
+
+  resolving cluster name "dup": there are 2 active clusters named "dup"; use --cluster-id to disambiguate
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/cluster-name-check/output.txt

@@ -1,11 +1,5 @@
 
 >>> [CLI] environments setup-local --cluster-name my-cluster --dry-run
-preflight  ok  check
-resolve    ok  source=cluster envKey=dbr/15.4.x-scala2.12
-fetch      ok  source=[DATABRICKS_URL]/dbr/15.4.x-scala2.12/pyproject.toml fromCache=false
-merge      ok
-provision  ok
-validate   ok
 Plan: [TEST_TMP_DIR]/pyproject.toml
   changed region: requires-python
   changed region: tool.uv.constraint-dependencies

acceptance/localenv/cluster-name-unknown/output.txt

@@ -1,7 +1,5 @@
-preflight  ok  check
-resolve    error  resolving cluster name "nope": no active cluster named "nope"
-fetch      pending
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed while resolving your compute target.
+
+  resolving cluster name "nope": no active cluster named "nope"
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/env-unsupported/output.txt

@@ -1,7 +1,5 @@
-preflight  ok  check
-resolve    ok  source=cluster envKey=dbr/15.4.x-scala2.12
-fetch      error  no published environment for "dbr/15.4.x-scala2.12". If this is a new runtime, try the latest LTS target (e.g. --serverless-version 5 or a supported --cluster-id DBR): GET [DATABRICKS_URL]/dbr/15.4.x-scala2.12/pyproject.toml: environment key not found
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed while fetching constraints.
+
+  no published environment for "dbr/15.4.x-scala2.12". If this is a new runtime, try the latest LTS target (e.g. --serverless-version 5 or a supported --cluster-id DBR): GET [DATABRICKS_URL]/dbr/15.4.x-scala2.12/pyproject.toml: environment key not found
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/flag-conflict/output.txt

@@ -1,7 +1,5 @@
-preflight  error  invalid compute target flags: flags --cluster-id and --serverless-version are mutually exclusive; specify at most one
-resolve    pending
-fetch      pending
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed during preflight checks.
+
+  invalid compute target flags: flags --cluster-id and --serverless-version are mutually exclusive; specify at most one
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/help/output.txt

@@ -1,14 +1,20 @@
-Provision (or update) a local Python environment matched to a Databricks compute target.
+Set up a local Python environment that matches a Databricks cluster or serverless version, so code you run on your machine behaves the same as it does on Databricks.
 
-Resolves the target to an environment key, fetches the pinned Python version,
-databricks-connect version, and dependency constraints published for that key,
-then provisions a matched .venv with uv. A project with no pyproject.toml is
-initialized from scratch; an existing pyproject.toml is merged in place (its
-env-owned sections are refreshed, user-owned content is preserved).
+Use this when you want to develop or debug a Databricks project locally: it installs the matching Python version and a compatible databricks-connect, and pins your dependencies to versions known to work with your chosen compute. It creates or updates a .venv (managed by uv) in the current directory and records the setup in pyproject.toml, leaving the rest of your project untouched.
 
 Usage:
   databricks environments setup-local [flags]
 
+Examples:
+  # Match a serverless version
+  databricks environments setup-local --serverless-version 5
+
+  # Match an existing cluster by name
+  databricks environments setup-local --cluster-name my-cluster
+
+  # See what would change without writing anything
+  databricks environments setup-local --serverless-version 5 --dry-run
+
 Flags:
       --cluster-id string           cluster ID to use as the compute target
       --cluster-name string         cluster name to use as the compute target (resolved to an ID via the Clusters API)

acceptance/localenv/job-classic-check/output.txt

@@ -1,11 +1,5 @@
 
 >>> [CLI] environments setup-local --job-task 12345.ingest --dry-run
-preflight  ok  check
-resolve    ok  source=job envKey=dbr/15.4.x-scala2.12
-fetch      ok  source=[DATABRICKS_URL]/dbr/15.4.x-scala2.12/pyproject.toml fromCache=false
-merge      ok
-provision  ok
-validate   ok
 Plan: [TEST_TMP_DIR]/pyproject.toml
   changed region: requires-python
   changed region: tool.uv.constraint-dependencies

acceptance/localenv/job-serverless-check/output.txt

@@ -1,11 +1,5 @@
 
 >>> [CLI] environments setup-local --job-task 12345.transform --dry-run
-preflight  ok  check
-resolve    ok  source=job envKey=serverless/serverless-v3
-fetch      ok  source=[DATABRICKS_URL]/serverless/serverless-v3/pyproject.toml fromCache=false
-merge      ok
-provision  ok
-validate   ok
 Plan: [TEST_TMP_DIR]/pyproject.toml
   changed region: requires-python
   changed region: tool.uv.constraint-dependencies

acceptance/localenv/job-task-foreach/output.txt

@@ -1,11 +1,5 @@
 
 >>> [CLI] environments setup-local --job-task 12345.fanout --dry-run
-preflight  ok  check
-resolve    ok  source=job envKey=serverless/serverless-v3
-fetch      ok  source=[DATABRICKS_URL]/serverless/serverless-v3/pyproject.toml fromCache=false
-merge      ok
-provision  ok
-validate   ok
 Plan: [TEST_TMP_DIR]/pyproject.toml
   changed region: requires-python
   changed region: tool.uv.constraint-dependencies

acceptance/localenv/job-task-jobcluster/output.txt

@@ -1,11 +1,5 @@
 
 >>> [CLI] environments setup-local --job-task 12345.ingest --dry-run
-preflight  ok  check
-resolve    ok  source=job envKey=dbr/15.4.x-scala2.12
-fetch      ok  source=[DATABRICKS_URL]/dbr/15.4.x-scala2.12/pyproject.toml fromCache=false
-merge      ok
-provision  ok
-validate   ok
 Plan: [TEST_TMP_DIR]/pyproject.toml
   changed region: requires-python
   changed region: tool.uv.constraint-dependencies

acceptance/localenv/job-task-missing-key/output.txt

@@ -1,7 +1,5 @@
-preflight  ok  check
-resolve    error  specify a job task: job 12345 has multiple tasks; specify one: --job-task 12345.<task-key> (available: ingest, transform)
-fetch      pending
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed while resolving your compute target.
+
+  specify a job task: job 12345 has multiple tasks; specify one: --job-task 12345.<task-key> (available: ingest, transform)
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/job-task-unknown/output.txt

@@ -1,7 +1,5 @@
-preflight  ok  check
-resolve    error  resolving job task 12345.nope: job 12345 has no task "nope" (available: ingest)
-fetch      pending
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed while resolving your compute target.
+
+  resolving job task 12345.nope: job 12345 has no task "nope" (available: ingest)
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/job-task-unpinned/output.txt

@@ -1,7 +1,5 @@
-preflight  ok  check
-resolve    error  resolving job task 12345.transform: task "transform" of job 12345 binds environment "default", which records no environment version
-fetch      pending
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed while resolving your compute target.
+
+  resolving job task 12345.transform: task "transform" of job 12345 binds environment "default", which records no environment version
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/manager-unsupported/output.txt

@@ -1,7 +1,5 @@
-preflight  error  detected a conda project; automated setup for conda is not yet available (P1). Use a uv project (add a pyproject.toml with a [tool.uv] table, or run `uv init`) to provision automatically
-resolve    pending
-fetch      pending
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed during preflight checks.
+
+  detected a conda project; automated setup for conda is not yet available (P1). Use a uv project (add a pyproject.toml with a [tool.uv] table, or run `uv init`) to provision automatically
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/merge-warnings/output.txt

@@ -1,11 +1,5 @@
 
 >>> [CLI] environments setup-local --serverless-version 4 --dry-run
-preflight  ok  check
-resolve    ok  source=serverless envKey=serverless/serverless-v4
-fetch      ok  source=[DATABRICKS_URL]/serverless/serverless-v4/pyproject.toml fromCache=false
-merge      ok
-provision  ok
-validate   ok
 warning: requires-python ">=3.10" is replaced by the environment's ">=3.12"
 warning: databricks-connect "databricks-connect~=16.0.0" is replaced by the environment's "databricks-connect~=17.2.0"
 warning: databricks-connect "databricks-connect==15.0.0" is not rewritten by the merge; the environment's "databricks-connect~=17.2.0" sits in "dev" alongside it, and no version satisfies both

acceptance/localenv/no-target/output.txt

@@ -1,7 +1,5 @@
-preflight  ok  uv [UV_VERSION]
-resolve    error  No compute target is selected. Select a cluster or serverless target, or pass --cluster-id / --cluster-name / --serverless-version / --job-task
-fetch      pending
-merge      pending
-provision  pending
-validate   pending
-For more detail, re-run with --debug, or --output json to share a structured report.
+✗ Setup failed while resolving your compute target.
+
+  No compute target is selected. Select a cluster or serverless target, or pass --cluster-id / --cluster-name / --serverless-version / --job-task
+
+Re-run with --debug for details, or --output json for a structured report.

acceptance/localenv/serverless-check/output.txt

@@ -1,11 +1,5 @@
 
 >>> [CLI] environments setup-local --serverless-version 4 --dry-run
-preflight  ok  check
-resolve    ok  source=serverless envKey=serverless/serverless-v4
-fetch      ok  source=[DATABRICKS_URL]/serverless/serverless-v4/pyproject.toml fromCache=false
-merge      ok
-provision  ok
-validate   ok
 Plan: [TEST_TMP_DIR]/pyproject.toml
   changed region: requires-python
   changed region: tool.uv.constraint-dependencies