Databricks CLI tutorial

  • Article

Note

This information applies to Databricks CLI versions 0.205 and above, which are in Public Preview. To find your version of the Databricks CLI, run databricks -v.

The Databricks command-line interface (also known as the Databricks CLI) utility provides an easy-to-use interface to automate the Azure Databricks platform from your terminal, command prompt, or automation scripts.

This article demonstrates how to use your local development machine to get started quickly with the Databricks CLI. See What is the Databricks CLI?.

The following hands-on tutorial assumes:

Complete the following steps:

  1. If it is not already installed, install the Databricks CLI as follows:

    Linux, macOS

    Use Homebrew to install the Databricks CLI by running the following two commands:

    brew tap databricks/tap
brew install databricks

    Windows

    You can use winget, Chocolatey or Windows Subsystem for Linux (WSL) to install the Databricks CLI. If you cannot use winget, Chocolatey, or WSL, you should skip this procedure and use the Command Prompt or PowerShell to install the Databricks CLI from source instead.

    Note

    Installing the Databricks CLI with Chocolatey is Experimental.

    To use winget to install the Databricks CLI, run the following two commands, and then restart your Command Prompt:

    winget search databricks
winget install Databricks.DatabricksCLI

    To use Chocolatey to install the Databricks CLI, run the following command:

    choco install databricks-cli

    To use WSL to install the Databricks CLI:

    1. Install curl and zip through WSL. For more information, see your operating system's documentation.

    2. Use WSL to install the Databricks CLI by running the following command:

      curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sh

  2. Confirm that the Databricks CLI is installed by running the following command, which displays the current version of the installed Databricks CLI. This version should be 0.205.0 or above:

    databricks -v

    Note

    If you run databricks but get an error such as command not found: databricks, or if you run databricks -v and a version number of 0.18 or below is listed, this means that your machine cannot find the correct version of the Databricks CLI executable. To fix this, see Verify your CLI installation.

After you install the Databricks CLI, complete the following steps:

Note

This tutorial assumes that you want to use OAuth user-to-machine (U2M) authentication to authenticate the CLI using your Azure Databricks user account. To configure the CLI to use other Databricks authentication types, see Authentication for the Databricks CLI.

  1. Use the Databricks CLI to initiate OAuth token management locally by running the following command for each target account or workspace.

    For account-level operations, in the following command, replace the following placeholders:

    databricks auth login --host <account-console-url> --account-id <account-id>

    For workspace-level operations, in the following command, replace <workspace-url> with your Azure Databricks per-workspace URL, for example https://adb-1234567890123456.7.databricks.azure.cn.

    databricks auth login --host <workspace-url>

  2. The Databricks CLI prompts you to save the information that you entered as an Azure Databricks configuration profile. Press Enter to accept the suggested profile name, or enter the name of a new or existing profile. Any existing profile with the same name is overwritten with the information that you entered. You can use profiles to quickly switch your authentication context among multiple accounts or workspaces.

    To get a list of any existing profiles, in a separate terminal or command prompt, use the Databricks CLI to run the command databricks auth profiles. To view a specific profile's existing settings, run the command databricks auth env --profile <profile-name>.

  3. In your web browser, complete the on-screen instructions to log in to your Azure Databricks account or workspace.

  4. To view a profile's current OAuth token value and the token's upcoming expiration timestamp, run one of the following commands:

    For account-level operations, run the following commands:

    • databricks auth token -p <profile-name>
    • databricks auth token --host <workspace-url> --account-id <account-id>
    • databricks auth token --host <workspace-url> --account-id <account-id> -p <profile-name>

    If you have multiple profiles with the same --host and --account-id values, you might need to specify the --host, --account-id, and -p options together to help the Databricks CLI find the correct matching OAuth token information.

    For workspace-level operations, run the following commands:

    • databricks auth token -p <profile-name>
    • databricks auth token --host <workspace-url>
    • databricks auth token --host <workspace-url> -p <profile-name>

    If you have multiple profiles with the same --host values, you might need to specify the --host and -p options together to help the Databricks CLI find the correct matching OAuth token information.

Next steps

After you set up the Databricks CLI: