Detect Databricks CLI version to gate --profile support

`--profile` on `databricks auth token` is a global Cobra flag, so old
CLIs (< v0.207.1) silently accept it and fail later with `cannot fetch
credentials` instead of `unknown flag: --profile`. The previous
error-based fallback never matched, leaving the `--host` fallback as
dead code.

This commit replaces the runtime fallback chain with version-based
capability detection:

* `CliVersion` carries a (major, minor, patch) triple plus an
  `UNKNOWN` sentinel and a default-dev-build (0,0,0) check.
* `DatabricksCliCredentialsProvider` runs `databricks version --output
  json` once per CLI path (cached on success only, with a 5s timeout)
  and gates `--profile` on >= v0.207.1; everything else falls back to
  `--host` with a precise warning.
* `CliTokenSource` is simplified to a single `cmd`; the
  `fallbackCmd` parameter and the runtime "unknown flag" retry loop are
  removed.

Mirrors the equivalent refactors in the Go and Python SDKs:
* databricks/databricks-sdk-go#1605
* databricks/databricks-sdk-py#1377

Co-authored-by: Isaac

Author: mihaimitrea-db

NEXT_CHANGELOG.md

@@ -7,11 +7,13 @@
 ### Breaking Changes
 
 ### Bug Fixes
+* Fixed Databricks CLI `--profile` fallback by detecting the CLI version at init time. The previous error-based detection was broken because `--profile` is a global Cobra flag silently accepted by old CLIs.
 
 ### Security Vulnerabilities
 
 ### Documentation
 
 ### Internal Changes
+* Detect Databricks CLI version at init time via `databricks version --output json`, enabling version-gated flag support. Successful detections are cached per CLI path; subprocess failures fall back to the most conservative command and are retried on the next call.
 
 ### API Changes

databricks-sdk-java/src/main/java/com/databricks/sdk/core/CliTokenSource.java

@@ -30,11 +30,6 @@ public class CliTokenSource implements TokenSource {
   private String accessTokenField;
   private String expiryField;
   private Environment env;
-  // fallbackCmd is tried when the primary command fails with "unknown flag: --profile",
-  // indicating the CLI is too old to support --profile. Can be removed once support
-  // for CLI versions predating --profile is dropped.
-  // See: https://github.com/databricks/databricks-sdk-go/pull/1497
-  private List<String> fallbackCmd;
 
   /**
    * Internal exception that carries the clean stderr message but exposes full output for checks.
@@ -58,24 +53,11 @@ public CliTokenSource(
       String accessTokenField,
       String expiryField,
       Environment env) {
-    this(cmd, tokenTypeField, accessTokenField, expiryField, env, null);
-  }
-
-  public CliTokenSource(
-      List<String> cmd,
-      String tokenTypeField,
-      String accessTokenField,
-      String expiryField,
-      Environment env,
-      List<String> fallbackCmd) {
-    super();
     this.cmd = OSUtils.get(env).getCliExecutableCommand(cmd);
     this.tokenTypeField = tokenTypeField;
     this.accessTokenField = accessTokenField;
     this.expiryField = expiryField;
     this.env = env;
-    this.fallbackCmd =
-        fallbackCmd != null ? OSUtils.get(env).getCliExecutableCommand(fallbackCmd) : null;
   }
 
   /**
@@ -158,22 +140,6 @@ public Token getToken() {
     try {
       return execCliCommand(this.cmd);
     } catch (IOException e) {
-      String textToCheck =
-          e instanceof CliCommandException
-              ? ((CliCommandException) e).getFullOutput()
-              : e.getMessage();
-      if (fallbackCmd != null
-          && textToCheck != null
-          && textToCheck.contains("unknown flag: --profile")) {
-        LOG.warn(
-            "Databricks CLI does not support --profile flag. Falling back to --host. "
-                + "Please upgrade your CLI to the latest version.");
-        try {
-          return execCliCommand(this.fallbackCmd);
-        } catch (IOException fallbackException) {
-          throw new DatabricksException(fallbackException.getMessage(), fallbackException);
-        }
-      }
       throw new DatabricksException(e.getMessage(), e);
     }
   }

databricks-sdk-java/src/main/java/com/databricks/sdk/core/DatabricksCliCredentialsProvider.java

@@ -6,12 +6,19 @@
 import com.databricks.sdk.core.oauth.OAuthHeaderFactory;
 import com.databricks.sdk.core.oauth.Token;
 import com.databricks.sdk.core.oauth.TokenSource;
+import com.databricks.sdk.core.utils.Environment;
 import com.databricks.sdk.core.utils.OSUtils;
 import com.databricks.sdk.support.InternalApi;
 import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import java.io.IOException;
+import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
 import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.TimeUnit;
+import org.apache.commons.io.IOUtils;
 
 @InternalApi
 public class DatabricksCliCredentialsProvider implements CredentialsProvider {
@@ -22,6 +29,18 @@ public class DatabricksCliCredentialsProvider implements CredentialsProvider {
 
   private static final ObjectMapper MAPPER = new ObjectMapper();
 
+  // --profile support added in CLI v0.207.1: https://github.com/databricks/cli/pull/855
+  static final DatabricksCliVersion CLI_VERSION_FOR_PROFILE = new DatabricksCliVersion(0, 207, 1);
+
+  // 5-second cap on `databricks version` so a hung CLI (slow first-run scan, antivirus, blocked
+  // stdin) does not wedge SDK init indefinitely.
+  private static final long VERSION_PROBE_TIMEOUT_SECONDS = 5;
+
+  // Successful version probes keyed by cliPath. Failures are deliberately not cached, so a
+  // transient error (timeout, AV scan) does not pin every later token source to the conservative
+  // fallback for the rest of the process lifetime.
+  private static final Map<String, DatabricksCliVersion> VERSION_CACHE = new ConcurrentHashMap<>();
+
   /** Thrown when the cached CLI token's scopes don't match the SDK's configured scopes. */
   static class ScopeMismatchException extends DatabricksException {
     ScopeMismatchException(String message) {
@@ -58,6 +77,150 @@ List<String> buildHostArgs(String cliPath, DatabricksConfig config) {
     return cmd;
   }
 
+  /**
+   * Builds the {@code auth token} command for the given CLI version.
+   *
+   * <p>Falls back to {@code --host} when {@code --profile} is either not configured or not
+   * supported by the installed CLI.
+   */
+  List<String> buildCliCommand(
+      String cliPath, DatabricksConfig config, DatabricksCliVersion version) {
+    if (config.getProfile() == null) {
+      return buildHostArgs(cliPath, config);
+    }
+
+    // Flag --profile is a global CLI flag and is recognized for all commands even the ones that
+    // do not support it. Only use --profile in CLI versions known to support it in `auth token`.
+    if (!version.atLeast(CLI_VERSION_FOR_PROFILE)) {
+      if (version.equals(DatabricksCliVersion.UNKNOWN) || version.isDefaultDevBuild()) {
+        // We didn't actually prove the CLI lacks --profile; we just failed to confirm it.
+        LOG.warn(
+            "Could not confirm --profile support for Databricks CLI {} (requires >= {}). "
+                + "Falling back to --host.",
+            version,
+            CLI_VERSION_FOR_PROFILE);
+      } else {
+        LOG.warn(
+            "Databricks CLI {} does not support --profile (requires >= {}). Falling back to --host.",
+            version,
+            CLI_VERSION_FOR_PROFILE);
+      }
+      return buildHostArgs(cliPath, config);
+    }
+
+    return new ArrayList<>(
+        Arrays.asList(cliPath, "auth", "token", "--profile", config.getProfile()));
+  }
+
+  /**
+   * Detects the installed CLI version and builds the {@code auth token} command. Falls back to the
+   * most conservative command when version detection fails.
+   */
+  List<String> resolveCliCommand(String cliPath, DatabricksConfig config) {
+    DatabricksCliVersion version = getCliVersion(cliPath, config.getEnv());
+    if (version.isDefaultDevBuild()) {
+      // A default-marker dev build has no injected version, so every feature gate fails.
+      // Surface an informational hint so users know why their feature flags aren't taking effect.
+      LOG.info(
+          "Databricks CLI {} is a development build; feature detection will use conservative "
+              + "fallbacks. Rebuild the CLI with an explicit version to enable capability-based "
+              + "flag selection.",
+          version);
+    }
+    return buildCliCommand(cliPath, config, version);
+  }
+
+  /**
+   * Returns the CLI version, catching subprocess failures so the caller can proceed with the
+   * conservative fallback. Successful results are cached per {@code cliPath} for the process
+   * lifetime; failures are not cached and will be retried on the next call.
+   */
+  DatabricksCliVersion getCliVersion(String cliPath, Environment env) {
+    DatabricksCliVersion cached = VERSION_CACHE.get(cliPath);
+    if (cached != null) {
+      return cached;
+    }
+
+    try {
+      DatabricksCliVersion version = probeCliVersion(cliPath, env);
+      VERSION_CACHE.put(cliPath, version);
+      return version;
+    } catch (Exception e) {
+      LOG.warn(
+          "Failed to detect Databricks CLI version: {}. Falling back to conservative flag set.",
+          e.getMessage());
+      return DatabricksCliVersion.UNKNOWN;
+    }
+  }
+
+  /**
+   * Runs {@code databricks version --output json} and returns the parsed {@link
+   * DatabricksCliVersion}.
+   */
+  DatabricksCliVersion probeCliVersion(String cliPath, Environment env) throws IOException {
+    List<String> versionArgs = Arrays.asList(cliPath, "version", "--output", "json");
+    List<String> cmd = OSUtils.get(env).getCliExecutableCommand(versionArgs);
+
+    ProcessBuilder pb = new ProcessBuilder(cmd);
+    pb.environment().putAll(env.getEnv());
+    Process process = pb.start();
+
+    try {
+      if (!process.waitFor(VERSION_PROBE_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
+        process.destroyForcibly();
+        throw new IOException(
+            "timed out after "
+                + VERSION_PROBE_TIMEOUT_SECONDS
+                + "s waiting for `databricks version`");
+      }
+    } catch (InterruptedException e) {
+      Thread.currentThread().interrupt();
+      throw new IOException("interrupted waiting for `databricks version`", e);
+    }
+
+    if (process.exitValue() != 0) {
+      String stderr = readStream(process.getErrorStream());
+      throw new IOException(
+          "`databricks version` exited with code " + process.exitValue() + ": " + stderr);
+    }
+
+    return parseCliVersion(readStream(process.getInputStream()));
+  }
+
+  private static String readStream(InputStream stream) throws IOException {
+    return new String(IOUtils.toByteArray(stream), StandardCharsets.UTF_8);
+  }
+
+  /**
+   * Parses the JSON output of {@code databricks version --output json}.
+   *
+   * <p>Takes Major/Minor/Patch from the JSON's pre-parsed numeric fields. The Prerelease field and
+   * the Version string are intentionally ignored: for our feature-gate purposes the base triple is
+   * sufficient, and the (0, 0, 0) case already identifies the default dev build (a CLI built
+   * without version metadata leaves these fields at their zero defaults).
+   *
+   * <p>Returns {@link DatabricksCliVersion#UNKNOWN} on failure so that an unparseable version
+   * disables every feature gate.
+   */
+  static DatabricksCliVersion parseCliVersion(String output) {
+    try {
+      JsonNode node = MAPPER.readTree(output);
+      JsonNode major = node.get("Major");
+      JsonNode minor = node.get("Minor");
+      JsonNode patch = node.get("Patch");
+      if (major == null || minor == null || patch == null) {
+        LOG.debug(
+            "Failed to parse Databricks CLI version: missing Major/Minor/Patch in {}", output);
+        return DatabricksCliVersion.UNKNOWN;
+      }
+      return new DatabricksCliVersion(major.asInt(), minor.asInt(), patch.asInt());
+    } catch (JsonProcessingException e) {
+      LOG.debug(
+          "Failed to parse Databricks CLI version from output: {} ({})", output, e.getMessage());
+      return DatabricksCliVersion.UNKNOWN;
+    }
+  }
+
   private CliTokenSource getDatabricksCliTokenSource(DatabricksConfig config) {
     String cliPath = config.getDatabricksCliPath();
     if (cliPath == null) {
@@ -68,25 +231,8 @@ private CliTokenSource getDatabricksCliTokenSource(DatabricksConfig config) {
       return null;
     }
 
-    List<String> cmd;
-    List<String> fallbackCmd = null;
-
-    if (config.getProfile() != null) {
-      // When profile is set, use --profile as the primary command.
-      // The profile contains the full config (host, account_id, etc.).
-      cmd =
-          new ArrayList<>(
-              Arrays.asList(cliPath, "auth", "token", "--profile", config.getProfile()));
-      // Build a --host fallback for older CLIs that don't support --profile.
-      if (config.getHost() != null) {
-        fallbackCmd = buildHostArgs(cliPath, config);
-      }
-    } else {
-      cmd = buildHostArgs(cliPath, config);
-    }
-
-    return new CliTokenSource(
-        cmd, "token_type", "access_token", "expiry", config.getEnv(), fallbackCmd);
+    List<String> cmd = resolveCliCommand(cliPath, config);
+    return new CliTokenSource(cmd, "token_type", "access_token", "expiry", config.getEnv());
   }
 
   @Override

databricks-sdk-java/src/main/java/com/databricks/sdk/core/DatabricksCliVersion.java

@@ -0,0 +1,93 @@
+package com.databricks.sdk.core;
+
+import com.databricks.sdk.support.InternalApi;
+import java.util.Objects;
+
+/**
+ * Semver version triple of the Databricks CLI used for capability gating.
+ *
+ * <p>Three sentinel states in the (major, minor, patch) tuple:
+ *
+ * <ul>
+ *   <li>{@code (-1, -1, -1)} — the {@link #UNKNOWN} sentinel, meaning version detection failed. It
+ *       compares less than every real release so every feature gate fails.
+ *   <li>{@code (0, 0, 0)} — the CLI's default dev build, emitted when the binary was built without
+ *       version metadata. See {@link #isDefaultDevBuild()}.
+ *   <li>anything else — a real CLI version.
+ * </ul>
+ *
+ * <p>Prerelease tags are deliberately ignored: feature gates are release-based, so a prerelease of
+ * a version with a flag is assumed to have the flag too.
+ */
+@InternalApi
+public final class DatabricksCliVersion implements Comparable<DatabricksCliVersion> {
+  public static final DatabricksCliVersion UNKNOWN = new DatabricksCliVersion(-1, -1, -1);
+
+  private final int major;
+  private final int minor;
+  private final int patch;
+
+  public DatabricksCliVersion(int major, int minor, int patch) {
+    this.major = major;
+    this.minor = minor;
+    this.patch = patch;
+  }
+
+  public int getMajor() {
+    return major;
+  }
+
+  public int getMinor() {
+    return minor;
+  }
+
+  public int getPatch() {
+    return patch;
+  }
+
+  /** Returns true when {@code this} is greater than or equal to {@code other}. */
+  public boolean atLeast(DatabricksCliVersion other) {
+    return compareTo(other) >= 0;
+  }
+
+  /**
+   * Returns true when the version is the CLI's default dev build {@code (0, 0, 0)}. A CLI built
+   * without version metadata leaves these fields at their zero defaults.
+   */
+  public boolean isDefaultDevBuild() {
+    return major == 0 && minor == 0 && patch == 0;
+  }
+
+  @Override
+  public int compareTo(DatabricksCliVersion o) {
+    int c = Integer.compare(major, o.major);
+    if (c != 0) return c;
+    c = Integer.compare(minor, o.minor);
+    if (c != 0) return c;
+    return Integer.compare(patch, o.patch);
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (!(o instanceof DatabricksCliVersion)) return false;
+    DatabricksCliVersion that = (DatabricksCliVersion) o;
+    return major == that.major && minor == that.minor && patch == that.patch;
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(major, minor, patch);
+  }
+
+  @Override
+  public String toString() {
+    if (equals(UNKNOWN)) {
+      return "unknown";
+    }
+    if (isDefaultDevBuild()) {
+      return "v0.0.0-dev";
+    }
+    return "v" + major + "." + minor + "." + patch;
+  }
+}