Databricks CLIは、ワークスペースのジョブ、ファイル、クラスタ、アプリをターミナルから操作するための公式コマンドラインツールです。ジョブやパイプラインの定義をYAMLで管理し、開発環境と本番環境へ同じ手順でデプロイする仕組み(Declarative Automation Bundles、旧名Databricks Asset Bundles)の入口でもあります。この記事では2026年11月15日時点の公式ドキュメントをもとに、インストールと旧CLIからの移行、OAuthでの認証プロファイル、よく使う操作、databricks.ymlの書き方、GitHub ActionsからのCI/CDまでをコード付きで整理します。
まとめ:Databricks CLIは1.x系をOAuthで認証し、デプロイはバンドルに寄せる
押さえることは3つです。1つ目は、pipで入れる旧CLI(0.18以下)ではなく、Goで書かれた新CLIを使うことです。2026年11月11日に公開された最新版は1.26.0で、1.0.0以降が一般提供の扱いになっています。2つ目は、認証をトークンの貼り付けではなくOAuthにすることです。手元ではdatabricks auth login、CI/CDではサービスプリンシパルとワークロードID連携を使います。
3つ目は、ジョブを画面で作り込まず、バンドルのdatabricks.ymlに書いてdatabricks bundle deployで反映することです。変更がGitに残り、レビューを通してから本番に出せます。Databricksの全体像と料金の考え方は、親記事のDatabricksとは?できること・DBU課金の料金と業種別の費用・導入事例にまとめています。
Databricks CLIのインストール手順とバージョン確認・旧CLIからの移行
最初にCLI本体を入れ、新旧どちらのCLIが動いているかを確かめます。検索で見つかる古い記事には旧CLIの手順が混ざっているため、ここで取り違えると後の認証やバンドルの手順が通りません。
macOS・Linux・Windows別のDatabricks CLI導入コマンド
公式のインストール手順(2026年9月11日更新)にあるコマンドは次のとおりです。WindowsではWSL上でLinuxの手順を使う方法が推奨とされています。
# macOS(Homebrew)
brew install databricks/tap/databricks
# Linux・WSL(unzipが必要。/usr/local/binに書けなければsudoを付ける)
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sh
# Windows(WinGet)
winget install Databricks.DatabricksCLI
# 版の確認(0.205.0以上なら新CLI)
databricks -v
# 更新
brew upgrade databricks
winget upgrade Databricks.DatabricksCLI
Homebrewでtapを先に追加する手順を使う場合、Homebrew 6.0.0以降ではbrew trust databricks/tapの実行が追加で必要です。curlで入れた版を更新するときは、既存の実行ファイルを消してからインストールのコマンドを流し直します。
databricks -vで新CLIか確かめ、pip版の旧CLIを外す手順
移行ガイド(2026年11月11日更新)によると、pip install databricks-cliで入る0.18以下の旧CLIは、Databricksのサポート窓口の対象外です。両方が入っているとPATHの順序で先に見つかった方が動くため、次の手順で整理します。
# どこにdatabricksがあるかを全部出す(Windowsは where databricks)
which -a databricks
# 旧CLIを外す(環境によってはpip3)
pip uninstall databricks-cli
旧CLIのスクリプトを移すときは、コマンド名と引数の違いに注意します。代表的な違いは次のとおりです。
runs list・runs get→jobs list-runs・jobs get-runfs mkdirs→fs mkdirsecrets list→secrets list-secretsclusters get --cluster-id 1234→clusters get 1234(IDは位置引数で渡す)unity-catalog schemas→schemas(接頭辞を付けない)
新CLIでは-oが出力形式の指定に変わり、ログの詳しさは--log-level debugで上げます。
Databricks CLIの認証設定:OAuth U2M・M2Mとプロファイルの切り替え
CLIの認証ページ(2026年10月30日更新)が挙げる方式は、人が使うOAuth U2M、サービスプリンシパルが使うOAuth M2M、レガシー扱いの個人アクセストークン(PAT)の3つです。公式はPATよりOAuthを推奨しており、OAuthのトークンは1時間で失効します。
auth loginで開発者のワークスペースへOAuth U2Mでログインする
# ブラウザが開き、ログインするとプロファイルが保存される
databricks auth login --host https://dbc-xxxxxxxx-xxxx.cloud.databricks.com --profile dev
# 保存されたプロファイルと有効かどうか(Name・Host・Valid)を一覧する
databricks auth profiles
# どのユーザーと方式で認証されているかを確かめる
databricks auth describe -p dev
databricks current-user me -p dev
CLI 1.0.0以降では、U2Mのトークンは既定でOSの資格情報ストアに保存されます。OSの保存先を使えない環境で従来どおりファイルに置く場合は、.databrickscfgの[__settings__]にauth_storage = plaintextを書くか、環境変数DATABRICKS_AUTH_STORAGE=plaintextを設定します。
.databrickscfgに複数プロファイルを書き、-pと環境変数で切り替える
プロファイルのページのとおり、設定ファイルはmacOSとLinuxでは~/.databrickscfg、Windowsでは%USERPROFILE%\.databrickscfgです。開発と本番のワークスペースを並べて書いておき、コマンドごとに-pで選びます。
[__settings__]
default_profile = dev
[dev]
host = https://dbc-xxxxxxxx-xxxx.cloud.databricks.com
auth_type = databricks-cli
[prod-sp]
host = https://dbc-yyyyyyyy-yyyy.cloud.databricks.com
client_id = 00000000-0000-0000-0000-000000000000
client_secret = (サービスプリンシパルのOAuthシークレット)
プロファイルを指定しないときに使われるのは、環境変数DATABRICKS_CONFIG_PROFILE、[__settings__]のdefault_profile、DEFAULTプロファイルの順で最初に見つかったものです。本番に向けたつもりが開発に流れた、という事故を防ぐには、本番のプロファイルを既定にせず、毎回-pで明示する運用にします。
サービスプリンシパルのOAuth M2Mで非対話の実行環境を認証する
夜間バッチや運用スクリプトのように人がログインできない場面では、サービスプリンシパルのクライアントIDとOAuthシークレットで認証します。設定ファイルを置けないコンテナでは、統一認証の環境変数で同じ値を渡せます。
export DATABRICKS_HOST=https://dbc-yyyyyyyy-yyyy.cloud.databricks.com
export DATABRICKS_CLIENT_ID=00000000-0000-0000-0000-000000000000
export DATABRICKS_CLIENT_SECRET="$(cat /run/secrets/dbx_sp_secret)"
export DATABRICKS_AUTH_TYPE=oauth-m2m
databricks current-user me
CLIが認証情報を探す順序は、バンドルの設定ファイル、環境変数、.databrickscfgのプロファイルです。見つかった時点で探索をやめるため、環境変数が残っているとプロファイルの指定より優先されることがあります。認証先が想定と違うときは、databricks auth describeで値の出どころを確かめます。
Databricks CLIでジョブ・ファイル・ワークスペースを操作するコマンド例
コマンドの一覧(2026年10月28日更新)には、jobs、fs、workspace、clusters、apps、apiなどのグループが並びます。日々の運用でよく使う形を示します。
jobs run-nowとlist-runsでジョブを実行し、JSON出力をjqで絞る
# ジョブIDと名前だけを一覧する(-o jsonで機械処理しやすい形にする)
databricks jobs list -p dev -o json | jq -r '.[] | "\(.job_id)\t\(.settings.name)"'
# ジョブを実行する。待たずに戻すなら --no-wait
databricks jobs run-now 123456789012345 -p dev
# 直近の実行結果を確かめる
databricks jobs list-runs --job-id 123456789012345 --limit 5 -p dev -o json
# 専用コマンドが無い操作はREST APIを直接呼べる
databricks api get "/api/2.1/jobs/get?job_id=123456789012345" -p dev
シェルスクリプトから呼ぶときは、出力を-o jsonに固定します。既定のtext形式は人が読むための表で、項目の並びが版によって変わる可能性があるためです。CLIを使わずに画面からジョブを作り、スケジュールとパラメータを設定する手順はDatabricksの使い方:ノートブック作成からDeltaテーブル・ジョブ化までの手順で解説しています。SQLウェアハウスの作成とクエリの実行はDatabricks SQLの使い方:SQLウェアハウスの種類・サイズ設計とクエリ実行例にまとめています。CLIを入れられない外部の業務システムからREST APIやPython SDKでジョブを起動する方法はDatabricks APIの使い方:REST API・Python SDKでのジョブ実行とOAuth M2M認証で解説しています。
fsとworkspaceでボリュームのファイルとノートブックを出し入れする
# Unity Catalogのボリュームへ手元のCSVを送る
databricks fs cp ./orders.csv dbfs:/Volumes/main/raw/landing/orders.csv -p dev
databricks fs ls dbfs:/Volumes/main/raw/landing -p dev
# ノートブックをソース形式で書き出し、Gitで差分を追えるようにする
databricks workspace export /Workspace/Shared/etl/daily_orders ./daily_orders.py --format SOURCE -p dev
ボリュームへの書き込みには、カタログとスキーマの利用権限とボリュームの書き込み権限が要ります。権限の継承はUnity Catalogとは?3レベル名前空間と権限継承・移行判断で解説しています。Databricks Appsの作成とデプロイも同じCLIのappsグループで行い、手順はDatabricks Appsの使い方にまとめました。
Declarative Automation Bundlesでジョブをコード管理する
ジョブのコード管理では、設定ファイルのdatabricks.ymlに定義を記述します。
公式の概要ページ(2026年11月5日更新)によると、Declarative Automation Bundlesは旧名Databricks Asset Bundlesで、ジョブ、パイプライン、ダッシュボード、モデルサービングのエンドポイントなどをYAMLで定義し、CLIで検証・デプロイ・実行する仕組みです。CLIはv0.218.0以上が必要です。
bundle initで雛形を作り、devとprodのターゲットを書き分ける
databricks bundle initを実行し、テンプレートに既定のdefault-pythonを選ぶと、databricks.ymlとサンプルのジョブが生成されます。ターゲットの部分を開発と本番に分けて書くと、次の形になります。
bundle:
name: sales_etl
include:
- resources/*.yml
targets:
dev:
mode: development
default: true
workspace:
host: https://dbc-xxxxxxxx-xxxx.cloud.databricks.com
prod:
mode: production
git:
branch: main
workspace:
host: https://dbc-yyyyyyyy-yyyy.cloud.databricks.com
root_path: /Workspace/Shared/.bundle/${bundle.name}/${bundle.target}
run_as:
service_principal_name: 00000000-0000-0000-0000-000000000000
デプロイモードのページによると、mode: developmentではリソース名の先頭に[dev ユーザー名]が付き、スケジュールとトリガーは一時停止し、ジョブの同時実行が有効になります。開発者ごとに同じワークスペースへデプロイしても、互いのジョブを上書きしません。mode: productionでは、現在のGitブランチがターゲットに書いたブランチと一致するかが検証され、実行主体にはサービスプリンシパルが推奨されています。
validate・deploy・run・destroyの順で開発ターゲットに反映する
ジョブのチュートリアルと同じ順序で、開発ターゲットに出して動かし、片付けます。
databricks bundle validate # YAMLと参照の検証
databricks bundle deploy --target dev # 開発ワークスペースへ反映
databricks bundle run --target dev sample_job
databricks bundle destroy --target dev # 検証が済んだら消す
本番への反映は手元から行わず、次の章のCI/CDに任せます。手元の権限で本番に出せる状態を残すと、レビューを通っていない変更が本番に入る経路が残るためです。
GitHub ActionsのOIDC連携とbundle deployによる本番反映
DatabricksのGitHub Actionsのページ(2026年11月4日更新)は、CI/CDの認証にワークロードID連携を推奨しています。GitHubが発行するOIDCトークンをDatabricksのトークンに交換するので、OAuthシークレットをGitHubに保存する必要がありません。
シークレット不要のワークロードID連携でprodへデプロイするワークフロー
前提として、Databricksのアカウントでサービスプリンシパルを作り、GitHub Actions向けのフェデレーションポリシーを設定します。ポリシーのsubjectは、GitHubが発行するトークンの値と完全に一致している必要があります。2026年7月15日より前に作られたリポジトリならrepo:<組織>/<リポジトリ>:environment:prodの形で、それ以降のリポジトリは数値の組織IDとリポジトリIDを含む形です。
# .github/workflows/deploy_prod.yml
name: deploy-prod
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
environment: prod # フェデレーションポリシーのsubjectと合わせる
permissions:
id-token: write # ワークロードID連携に必要
contents: read
env:
DATABRICKS_AUTH_TYPE: github-oidc
DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
DATABRICKS_CLIENT_ID: ${{ secrets.DATABRICKS_CLIENT_ID }} # サービスプリンシパルのUUID
steps:
- uses: actions/checkout@v4
- uses: databricks/[email protected] # 版を固定する
- run: databricks bundle validate --target prod
- run: databricks bundle deploy --target prod
公式ページのバンドルの例はサービスプリンシパルのトークンをDATABRICKS_TOKENで渡す形で、ワークロードID連携に置き換えるときはid-token: writeを足し、トークンをDATABRICKS_AUTH_TYPE・DATABRICKS_HOST・DATABRICKS_CLIENT_IDに替えると案内されています。上のワークフローはその指示どおりに組み直したものです。AWSでの同じ考え方はTerraformをGitHub Actionsで自動化しAWSへ反映する手順でも扱っています。
setup-cliの版固定とv1.20.0のTerraformエンジン削除への備え
setup-cliを@mainで参照すると、CIが動くたびに最新のCLIが入ります。CLIの更新は速く、v1.26.0は2026年11月11日の公開です。版を固定し、更新は開発ターゲットで確かめてから上げる運用にします。
実際に互換性が切れた例もあります。v1.20.0のリリースノートでは、バンドルのTerraformデプロイエンジンが削除され、bundle.engine: terraformを指定するとエラーになりました。Terraformで出し続けたい場合はv1.19.x系を使うよう案内されています。古いバンドルを引き継いだ場合は、この設定が残っていないかを先に確かめます。
Databricks CLI・バンドルの採用条件と画面・Terraformで足りる場面
判断の軸は、変更を誰がどの頻度で行うかと、扱う対象がDatabricksの中か外かの2つです。
複数人と複数ワークスペースでジョブを変更するならバンドルを採用する判断
採用すべきなのは、開発と本番でワークスペースを分けていて、ジョブやパイプラインを複数人で変更する体制です。画面で作ったジョブは、誰がいつ何を変えたかが残らず、本番と開発の設定がずれていきます。バンドルなら変更はプルリクエストで確認でき、本番への反映はサービスプリンシパルが行うため、個人の権限で本番を変える経路を閉じられる仕組みです。VS CodeやGitHub Copilotから同じワークスペースを操作する設定は、GitHub CopilotでDatabricks開発を進める方法で解説しています。
単発の操作やクラウド基盤の構築ではCLIとバンドルを見送る判断
次の場合は、CLIやバンドルにこだわりません。
- 1回だけの確認や試行で、再現する必要が無い(画面で十分)
- ワークスペースそのもの、VPC、IAMロール、S3などクラウド側の構築(Terraform providerやクラウドの仕組みで管理する)
- ジョブが数本で、変更する人が1人しかいない(CLIのスクリプトだけで足りる)
AWS側の構築手順はDatabricks on AWSの構築手順にまとめています。練習にはDatabricks Free EditionのワークスペースもCLIのログインと基本操作を試せる環境です。ワークスペースの設計からバンドルとCI/CDの整備、権限設計までまとめて任せたい場合は、一創のデータ分析基盤構築・MLOps構築支援で引き受けています。
Databricks CLIの導入と認証で詰まりやすい点のよくある質問
databricks cli を使い始めるときによく聞かれる質問に、2026年11月15日時点の公式ドキュメントをもとに答えます。
pipで入れたdatabricks-cliと今のDatabricks CLIは何が違いますか?
別物です。pip install databricks-cliで入るのは0.18以下の旧CLIで、Databricksのサポート対象に含まれません。今のCLIは0.205以上の新しい系統で、1.0.0以降が一般提供の扱いです。databricks -vの表示で見分けられます。旧CLIはコマンド名や引数の形が違うため、古いスクリプトは移行ガイドの対応表を見て書き換えます。
OAuthのトークンは1時間で切れますが、毎回ログインし直しますか?
通常は不要です。databricks auth loginで保存した認証情報をもとに、CLIが短い有効期限のトークンを扱います。プロファイルが使えなくなったときは、databricks auth profilesでValid列を確かめ、NOになっていればdatabricks auth loginによる再ログインが必要です。CIでは人のログインに頼らず、サービスプリンシパルのM2Mかワークロード ID連携を使います。
Databricks Asset BundlesとDeclarative Automation Bundlesは別の機能ですか?
同じ機能です。公式ドキュメントでは、Declarative Automation Bundlesが旧名Databricks Asset Bundlesであると明記されています。コマンドは今もdatabricks bundleで、設定ファイルもdatabricks.ymlのままです。検索ではAsset Bundlesの名前の記事が多く出ますが、手順を参照するときはCLIの版とリリースノートの変更点を合わせて確かめます。
WindowsではwingetとWSLのどちらで入れるべきですか?
公式のインストール手順では、WindowsはWSL上でLinuxのcurlの手順を使う方法が推奨とされています。バンドルのスクリプトやCIのワークフローはLinuxのシェルで動かすことが多いため、手元もWSLに揃える方法なら環境の差が出にくい構成です。PowerShellから直接使いたい場合はwinget install Databricks.DatabricksCLIで入れられます。
Terraform providerとバンドルはどう使い分けますか?
使い分けの判断基準は、管理する対象です。ワークスペースの作成、ネットワーク、IAMロール、ストレージなどクラウドとアカウントの土台はTerraform providerで管理します。その上で動くジョブ、パイプライン、ダッシュボード、アプリはバンドルで管理します。なおバンドル内部のTerraformデプロイエンジンはv1.20.0で削除されており、バンドルの裏でTerraformを使う設定はもう使えません。
関連記事
- Databricksとは?できること・DBU課金の料金と業種別の費用・導入事例【2026年10月】:Databricks全体の機能とDBU単価
- Databricks Appsの使い方:Streamlitアプリのデプロイ手順・認証・料金【2026年11月】:CLIのappsコマンドでのデプロイ
- Databricks on AWSの構築手順:クロスアカウントIAM・S3・VPCの設定とAzure版との違い【2026年11月】:CLIの接続先になるワークスペースの構築
- Databricks Free Editionの使い方:制限値・できないこと・有償版へ移る判断【2026年11月】:CLIを無料で試すときの上限
- Unity Catalogとは?3レベル名前空間と権限継承・移行判断を実装視点で解説【2026年版】:ボリュームとテーブルの権限