CLI Authentication

Skill: databricks-config

What You Can Build

Proper CLI authentication is the foundation for every bundle deployment, workspace administration command, and SDK integration. You’ll configure OAuth2 login (the only recommended method), manage named profiles for multi-workspace setups, and set the environment variables that the Python SDK and AI Dev Kit tools expect.

In Action

“Set up OAuth authentication for the Databricks CLI against my workspace, create a named profile, and verify the connection works.”

# Authenticate with OAuth (interactive browser flow)
databricks auth login \
  --host https://my-workspace.cloud.databricks.com \
  -p my-workspace

# Verify the token was stored
databricks auth token -p my-workspace

# Test the connection
databricks clusters list --profile my-workspace

Key decisions:

• OAuth over PATs, always — Personal Access Tokens are static secrets that can leak. OAuth tokens rotate automatically and integrate with your identity provider’s MFA
• Named profiles (-p my-workspace) store credentials in ~/.databrickscfg so you don’t pass --host on every command
• databricks auth token prints the current token for debugging — if it’s expired, re-run databricks auth login

More Patterns

Multi-Workspace Profile Setup

“Configure profiles for dev, staging, and prod workspaces so I can switch between them with a flag.”

# Set up each workspace
databricks auth login --host https://dev.cloud.databricks.com -p dev
databricks auth login --host https://staging.cloud.databricks.com -p staging
databricks auth login --host https://prod.cloud.databricks.com -p prod

# Use a specific workspace
databricks jobs list --profile prod

# Deploy bundles to different targets
databricks bundle deploy -t dev --profile dev
databricks bundle deploy -t prod --profile prod

Each profile is an independent credential stored in ~/.databrickscfg. You can have as many as you need, and they don’t interfere with each other.

SDK Authentication via Profile

“Configure the Python SDK to authenticate using a named profile instead of environment variables.”

from databricks.sdk import WorkspaceClient

# Use a named profile
w = WorkspaceClient(profile="my-workspace")

# Verify the connection
me = w.current_user.me()
print(f"Authenticated as: {me.user_name}")

The SDK checks multiple credential sources in order: explicit parameters, environment variables, then ~/.databrickscfg. Named profiles are the cleanest option when you work with multiple workspaces from the same machine.

Environment Variable Configuration

“Set the right environment variable so the SDK and CLI tools pick up my profile automatically.”

# Set the default profile for the SDK
export DATABRICKS_CONFIG_PROFILE=my-workspace

# Now all SDK calls use this profile without specifying it
python my_script.py

Use DATABRICKS_CONFIG_PROFILE (not DATABRICKS_PROFILE — that’s a common mistake that silently falls through to default credentials). This variable works for both the Python SDK and the CLI.

Profile File Format

“Show me what the ~/.databrickscfg file looks like after setting up profiles.”

[my-workspace]
host = https://my-workspace.cloud.databricks.com
auth_type = databricks-cli
cluster_id = 0123-456789-abcdef

[dev]
host = https://dev.cloud.databricks.com
auth_type = databricks-cli

[prod]
host = https://prod.cloud.databricks.com
auth_type = databricks-cli

The auth_type = databricks-cli entry tells the SDK to use the OAuth token managed by the CLI. The optional cluster_id field sets a default cluster for interactive sessions.

Watch Out For

• Using Personal Access Tokens (PATs) — PATs are static, long-lived secrets. If they leak into a repo, log file, or shell history, they grant full access until manually revoked. Use OAuth exclusively.
• Setting DATABRICKS_PROFILE instead of DATABRICKS_CONFIG_PROFILE — The SDK expects DATABRICKS_CONFIG_PROFILE. The wrong variable name causes a silent fallback to default credentials, which either fails or authenticates to the wrong workspace.
• Expired OAuth tokens without re-login — OAuth tokens expire. If CLI commands suddenly return cannot configure default credentials, run databricks auth login -p <profile> to refresh.
• Missing --profile in CI/CD — In automated environments, always pass --profile explicitly or set DATABRICKS_CONFIG_PROFILE. Relying on the default profile works on your laptop but breaks in a shared runner.