Wrangler CLI

解決する課題

Cloudflare Workersやその周辺リソースをダッシュボードの手作業だけで管理すると、変更の再現性やチームでの共有が難しくなります。Wrangler CLIは、Workersの開発・テスト・デプロイ・各種バインディング管理をコマンドとコードから行うための公式ツールで、開発体験の統一とデプロイの自動化を支えます。

• ローカルで本番に近い環境を再現しつつ開発したい → 内蔵のローカル開発サーバーで検証する
• 同じ手順を手作業で繰り返したくない → デプロイやリソース作成をコマンド化する
• KV・D1・R2などの関連リソースをまとめて管理したい → 設定ファイルとサブコマンドで一元管理する
• 複数環境(開発・ステージング・本番)を切り替えて運用したい → 環境設定とシークレット管理で使い分ける
• デプロイをCI/CDパイプラインに組み込みたい → 非対話的に実行できるコマンド体系を使う

Wranglerは、Cloudflareの管理APIを呼び出す薄いクライアントであり、OCIでいえばOCI CLI、AWSでいえばAWS CLI(に加えSAMやCDKの一部機能)に相当する立ち位置です。

主要概念と用語

• Wrangler: Node.js製の公式コマンドラインツール。wrangler <サブコマンド>という体系でWorkers関連の操作をほぼ網羅する
• wrangler.toml / wrangler.jsonc: プロジェクトのルートに置く設定ファイル。Worker名、実行環境、バインディング、ルートなどを宣言的に記述する
• バインディング (Binding): WorkerのコードからKV・D1・R2・Durable Objects・Queuesなどのリソースにアクセスするための接続設定
• 環境 (Environments): 設定ファイル内で開発・ステージング・本番などを名前付きブロックとして分離する仕組み
• シークレット (Secrets): APIキーなど機密情報を、設定ファイルに書かずに暗号化された状態で登録する仕組み
• wrangler dev: ローカルでWorkerを起動し、実際のランタイムに近い環境で動作確認できる開発サーバー
• wrangler deploy: コードと設定を検証し、Cloudflareのグローバルネットワークへ反映するコマンド
• wrangler tail: 稼働中Workerの実行ログをリアルタイムでストリーミング表示するコマンド
• アカウントID / APIトークン: Wranglerがどのアカウントに対してどの権限で操作するかを決める認証情報

仕様・制限・クォータ

• WranglerはNode.js環境上で動作するCLIで、npm/pnpm/yarn経由でプロジェクトごとに導入するか、グローバルに導入して使う
• 設定ファイルは**TOML形式(wrangler.toml)またはJSONC形式(wrangler.jsonc)**のいずれかを使い、プロジェクトごとに1つを採用する
• ローカル開発サーバーは実際の実行ランタイムに近いエミュレーションで動作するが、一部のネットワーク挙動やリージョン依存の振る舞いは本番と完全には一致しない場合がある
• デプロイ対象のWorkerサイズや同時にアタッチできるバインディング数にはサービス側の上限があり、大規模構成では分割やDurable Objectsの活用を検討する
• 認証はAPIトークンまたはOAuthログインで行い、トークンにはアカウント単位・権限単位のスコープを設定できる
• Wrangler自体の利用に追加料金はなく、課金はデプロイ先のWorkers実行やバインディングしたリソースの利用量に対して発生する
• バージョンアップに伴いサブコマンドや設定項目が追加・整理されることがあるため、既存プロジェクトの移行時は変更内容を確認する

内部の仕組み

Wranglerは、手元のコードと設定ファイルをCloudflareの管理APIへ橋渡しするクライアントです。wrangler dev実行時は、ローカルにWorkersランタイムに近い実行環境を立ち上げ、コードの変更を検知して自動的に再読み込みします。バインディングされたKVやD1などのリソースは、ローカルモードでは擬似的なストレージとして扱われるか、リモートのリソースに接続する設定を選べます。

wrangler deploy実行時は、設定ファイルの内容を検証したうえで、コードをビルド・バンドルし、署名済みのリクエストとしてCloudflareのAPIに送信します。API側はコードを受け取り、世界中のエッジロケーションへ配信します。バインディング(KV名前空間、D1データベース、R2バケットなど)は、事前にWrangler経由で作成しIDを設定ファイルに紐づけておくことで、デプロイ時に自動的に接続されます。

認証情報の供給方法は複数あります。

• OAuthログイン: wrangler loginでブラウザ経由の対話的な認証を行い、ローカルにトークンを保存する
• APIトークン: 環境変数や設定でAPIトークンを直接指定する方式。CI/CDや非対話的な実行に向く
• アカウントID指定: 複数アカウントに所属する場合、対象アカウントを明示的に指定する

設計パターン / ベストプラクティス

• 設定ファイルをバージョン管理に含め、環境ごとの差分をコードとして残す
• 環境(Environments)で開発・ステージング・本番を分離し、誤って本番に反映しないようにする
• シークレットは設定ファイルに書かず、専用コマンドで暗号化登録する
• CI/CDパイプラインではAPIトークンによる非対話的な認証を使い、権限は必要最小限のスコープに絞る
• ローカル開発とリモートリソースを使い分け、本番データに影響を与えない検証環境を用意する
• バインディングの命名はプロジェクト全体で一貫させ、複数Workerをまたぐ運用でも迷わないようにする
• デプロイ前にドライラン相当の検証(設定の構文チェックやローカル動作確認)を挟む

運用・監視

• wrangler tailで稼働中Workerのログをリアルタイム表示し、エラーや遅延の兆候を早期に把握する
• デプロイの失敗は設定ファイルの検証エラーや認証エラーであることが多く、まずコマンドの出力メッセージを確認する
• 認証エラー発生時は、APIトークンの有効期限やスコープ、対象アカウントIDの一致を確認する
• バインディングが反映されない場合は、設定ファイル内のリソースIDと実体の対応関係を見直す
• バージョン更新後に挙動が変わった場合は、**変更内容(サブコマンドの仕様変更など)**を確認してから設定を追随させる
• CI/CD上のデプロイ失敗は、終了コードとログ出力の両方をパイプラインの成否判定に反映する

コスト

Wrangler自体は無償のオープンソースツールであり、導入や実行に追加料金はかかりません。課金はWrangler経由でデプロイしたWorkersの実行量や、接続したKV・D1・R2などのリソースの利用量に対して発生します。

• CLIツールの利用そのものは無料。コストはデプロイ先のリソース利用に依存する
• ローカル開発サーバーでの検証はリモートリソースの課金対象呼び出しを避けられるため、コスト管理にも役立つ
• 誤って大量のリソースを作成・デプロイしないよう、設定ファイルのレビューを習慣化する

セキュリティ

• APIトークンは必要な権限スコープのみを付与し、リポジトリやログに残さない
• シークレットはWranglerの専用コマンドで暗号化登録し、設定ファイルへの平文記載を避ける
• CI/CD環境ではシークレットストアや環境変数管理機能を使い、トークンをジョブ実行時のみ注入する
• 開発者ごとに個別のAPIトークンを発行し、権限の追跡と失効を容易にする
• 不要になったトークンは速やかに失効させ、定期的に棚卸しする
• ローカル開発とリモートリソースの接続範囲を分け、誤って本番データに変更を加えるリスクを減らす

関連サービス・比較

Cloudflareを操作する手段として、GUIで直接設定変更を行うCloudflareダッシュボードとよく比較されます。コマンドとコードで手続き的に操作するWranglerと、画面操作で都度設定するダッシュボードの違いを押さえると使い分けやすくなります。

ハンズオン / CLI例

# 1) Wranglerを導入(プロジェクトローカル)
npm install --save-dev wrangler

# 2) 対話的にログイン(ブラウザでOAuth認証)
npx wrangler login

# 3) 新規Workerプロジェクトを作成
npx wrangler init my-worker

# 4) ローカル開発サーバーを起動(コード変更は自動反映)
npx wrangler dev

# 5) KV名前空間を作成し、設定ファイルにバインディングを追加
npx wrangler kv namespace create "MY_KV"

# 6) シークレットを暗号化登録(対話的に値を入力)
npx wrangler secret put API_KEY

# 7) 本番環境へデプロイ
npx wrangler deploy --env production

# 8) 稼働中Workerのログをリアルタイム表示
npx wrangler tail