Databricks CLIの接続と簡単な実行を試してみた
かわばたです。
DatabricksでのジョブやクラスターなどのリソースをGUIで管理していると、定型的な操作や確認の度にWebコンソールを開くのが手間に感じることがあります。Databricks CLIを使えば、ターミナルから直接Databricksの各種操作を行えるため、こうした手間を軽減できそうです。
今回、Databricks CLIのインストールから認証設定、基本的なコマンド実行までを試してみたので、手順と確認結果をまとめます。
背景・課題
Databricksの各種操作（クラスターの確認、ジョブの一覧取得、ワークスペースの操作など）は通常Webコンソールから行いますが、以下のような場面でCLIがあると便利です。
- 複数のリソースの状態をまとめて確認したい場合
- 定型操作をスクリプトとして自動化したい場合
- ターミナルで作業中にブラウザに切り替えずに操作を完結したい場合
技術的アプローチ
Databricks CLIは、Databricks REST APIをラップしたコマンドラインツールです。CLIを使うことで、APIを直接叩くことなく、シンプルなコマンドでDatabricksプラットフォームの各種リソースを操作できます。
主な機能は以下の通りです。
- クラスター管理: クラスターの一覧取得、詳細情報の確認、起動・停止
- ジョブ管理: ジョブの一覧取得、作成、実行
- ワークスペース操作: ワークスペース内のファイルやディレクトリの一覧取得、インポート・エクスポート
- シークレット管理: シークレットスコープの管理
- その他: ライブラリ管理、トークン管理、Unity Catalog操作など
制限事項
- 2026年3月28日時点では、Databricks CLIバージョン0.205以上が対象です（Public Preview）
- 従来版のCLI（バージョン0.18以下）とはコマンド体系が異なるため、従来版を利用していた場合は移行が必要です
コスト
- Databricks CLI自体の利用に追加コストは発生しません
- CLIから実行する各種操作（クラスター起動、ジョブ実行等）にはDatabricksの通常の利用料金が適用されます
前提条件
- Databricks: Free Edition
- ローカル環境: WSL
- インストール方法: curl（公式インストールスクリプト）
- 認証方式: OAuth User-to-Machine（U2M）認証（今回の検証環境で利用可能であることを確認）
- 必要な権限: Databricksワークスペースへのアクセス権限
事前準備
Databricks CLIのインストール
公式が提供するインストールスクリプトをcurlで取得・実行してインストールします。
curlがインストールされていることを確認します。
curl -V
※curlがインストールされていない場合は、ドキュメントにダウンロードリンクがありますのでそちらをご確認ください。
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sh
インストール後、バージョンを確認します。
databricks -v
バージョンがv0.295ということで、指定したバージョンのインストールができました。
試してみた
1. 認証設定（OAuth U2M認証）
Databricks CLIからワークスペースに接続するための認証設定を行います。今回はOAuth User-to-Machine（U2M）認証を使用します。U2M認証はブラウザベースの対話的なログインフローで、有効期限が1時間未満の短命トークンが発行されます。
auth loginで作成した接続先やプロファイル設定は、ホームディレクトリの.databrickscfgファイルに保存されます。なお、OAuth U2Mのアクセストークン自体はローカルキャッシュ（~/.databricks/token-cache.json）で管理されます。
以下のコマンドを実行します。<workspace-url>はDatabricksワークスペースのURLに置き換えてください。
databricks auth login --host <workspace-url>
実行すると、プロファイル名の入力を求められます。提案されたプロファイル名をそのまま使う場合はEnterを押します。任意の名前を入力することもできます。
表示されたURLをブラウザで開くと、Databricksの認証画面が表示されます。ログインを完了すると、CLI側の認証も完了します。
認証が成功したことを確認するには、以下のコマンドを使います。
databricks auth token -p <profile-name>
databricks auth env --profile <profile-name>
プロファイル一覧や認証情報が表示されればOKです。
2. プロファイルの確認と管理
認証設定が完了すると、.databrickscfgファイルにプロファイルが保存されます。プロファイルを使うことで、複数のワークスペースへの接続を管理できます。
設定済みのプロファイル一覧は以下のコマンドで確認できます。ホストURLや認証の有効状態が表形式で表示されます。
databricks auth profiles
特定のプロファイルの認証情報を詳しく確認したい場合は、以下のコマンドを実行します。認証タイプやホストURL、トークンの詳細が表示されます。
databricks auth env --profile <profile-name>
ワークスペースURLからプロファイルを逆引きすることもできます。
databricks auth env --host <workspace-url>
CLIコマンド実行時にプロファイルを指定するには、-p（--profile）フラグを使用します。
databricks clusters list -p <profile-name>
プロファイル一覧が正常に表示されればOKです。
3. 基本コマンドの実行
認証設定が完了したので、いくつかの基本コマンドを試してみます。
ワークスペースの内容一覧
databricks workspace list /
ワークスペースのルートディレクトリの内容が表示されればOKです。
パイプライン更新の開始
パイプラインの新しい更新実行を開始します。パイプラインに対して既にアクティブな更新が存在する場合、このリクエストは失敗し、アクティブな更新は引き続き実行されます。
databricks pipelines start-update PIPELINE_ID [flags]
ヘルプの活用
各コマンドの使い方がわからない場合は、-hオプションでヘルプを確認できます。
# 全コマンドグループを表示
databricks -h
# 特定のコマンドグループのコマンド一覧
databricks clusters -h
# 特定コマンドの詳細ヘルプ
databricks clusters list -h
最後に
Databricks CLIのインストールから認証設定、プロファイル管理、基本的なコマンド実行までを試してみました。
今回の検証では、Free Edition環境でもOAuth U2M認証を使ったブラウザベースの認証フローで簡単に接続設定が行えました。プロファイル機能を使えば、複数のワークスペースへの接続情報を.databrickscfgファイルで管理でき、-pフラグで切り替えられるのも便利です。
また、Claude Codeとの相性がとても良いと感じたので、ぜひ活用してみてください。
この記事が何かの参考になれば幸いです！
