wrangler

Wrangler CLI

このスキルは、プロジェクトに wrangler.jsonc、wrangler.json、または wrangler.toml があり、cloudflare.config.ts がない場合、またはユーザーが Wrangler を指定した場合にのみ使用してください。新規プロジェクト、cloudflare.config.ts があるプロジェクト、Cloudflare の設定がないプロジェクトでは、代わりに Cloudflare CLI（cf）を使用してください。インストールされている場合は cf-cli スキルを読み込むか、コーディングエージェントで cf を使用するに従ってください。これらのプロジェクトに Wrangler を追加しないでください。

コマンドや設定を書く前に、プロジェクトの Wrangler のバージョンを確認し、関連ドキュメントを取得してください。CLI のフラグと設定フィールドは変更されるため、記憶している例に頼らないでください。

プロジェクトを調査する

• パッケージマネージャー、インストール済みの Wrangler のバージョン、パッケージスクリプト、フレームワーク、Wrangler の設定を確認してください。ローカルのバージョンが使われるように、プロジェクトのスクリプトまたはパッケージマネージャーを通じてコマンドを実行してください。必要に応じて既存のロックファイルを使って依存関係をインストールしてください。現在のドキュメントに合わせるために、Wrangler を暗黙にアップグレードしないでください。プロジェクトに Wrangler の設定ファイルがあるものの、Wrangler が依存関係に含まれていない場合は、インストールガイドに従ってローカルに追加してください。
• ビルドまたはデプロイコマンドで使われる設定を、フレームワークが生成した設定も含めて特定してください。生成された出力ではなく、その元となる設定を編集してください。
• 設定を変更するコマンドを実行する前に、対象のアカウント、Worker、環境、リソースを確認してください。データ操作では、対象がローカルかリモートかを確認してください。

タスクに必要な情報を取得する

利用可能な場合は Cloudflare MCP の docs ツールを使うか、関連するリンク先のページを直接取得してください。該当するコマンドまたは製品の個別ページへのリンクをたどり、リファレンス全体を読み込まないでください。ページが移動している場合は、Wrangler コマンドインデックスまたは Cloudflare のドキュメント検索から探し直してください。

タスク	参照先
リソース管理、デプロイ、ロールバック、診断などのコマンドとフラグを確認する	プロジェクト内の wrangler --help と wrangler <command> --help；コマンドリファレンス
設定を編集する、またはバインディングを追加する	インストール済みの wrangler/config-schema.json（通常は node_modules 内）；設定リファレンス
フレームワークアプリケーションをデプロイする	フレームワークガイド；プロジェクトで既に使用しているフレームワークとアダプターに対応するガイドに従ってください
依頼に応じてアプリケーションを Workers に移行する	Pages から Workers への移行；Vercel から Workers への移行
ステージング環境または本番環境を設定する	環境
ローカル、CI、またはデプロイ済み Worker でシークレットを設定する	シークレット
バインディングとランタイムの型を生成する	TypeScript
ローカルで実行する、またはテスト方法を選ぶ	ローカル開発；テスト
Wrangler のロール、スコープ、API トークンの権限を選ぶ	ロールと権限；Workers のロールと権限
ブランチまたはプルリクエストの環境を作成、管理する	プレビューの概要；スタートガイド；設定
プレビューのリソースを分離するか共有するかを決める	現在の制限事項を含むリソースと分離
プレビュー URL、アクセス、デバッグ、または CI を設定する	カスタムドメイン；テストとデバッグ；例
プレビュー、バージョン URL、Wrangler 環境から選ぶ	ワークフローの比較
認証の問題を診断する、またはアカウントを選択する	whoami を含む一般コマンド；認証プロファイル
認証なしでプロトタイプをデプロイする	利用条件、期限、クレーム URL の処理についてはデプロイのクレームを参照してください。本番環境または CI では、永続的なアカウントを使用してください

ドキュメントに記載された機能がプロジェクトのバージョンに存在するかどうかは、インストール済みのヘルプとスキーマで確認してください。必要な機能の利用にアップグレードが必要な場合は、その依存関係を明記してください。情報を取得できない場合は、その不足を明示し、構文を捏造するのではなく、利用可能なローカル情報を使用してください。

変更を適用する

• 新しい設定には wrangler.jsonc を優先してください。新しいプロジェクトの互換性日付には今日の日付を設定し、既存プロジェクトの日付を進める場合は、ランタイムの変更を確認してテストしてください。既存のプロジェクト規約を維持し、付随的なフォーマット移行は避けてください。
• バインディングや変数を追加する前に、環境の継承を確認してください。環境ごとに個別に指定する必要があるフィールドもあります。デフォルト設定が動作していても、ステージング環境が設定済みとは限りません。
• Cloudflare Vite プラグインでは、開発時またはビルド時に CLOUDFLARE_ENV を使って環境を選択してください。生成されたビルドをデプロイしてください。デプロイ時に環境を設定しても、フラット化された設定の対象は切り替わりません。Vite 環境を参照してください。
• デプロイ前に、ダッシュボードでの変更を設定と整合させてください。Wrangler はダッシュボードの変数やルートを上書きすることがあります。既存のリソースをバインドする際は、その識別子を確認してください。識別子を省略すると、自動プロビジョニングが実行される可能性があります。
• 開発時は、ローカルシミュレーションとリモートバインディングを区別してください。ローカルで実行中の Worker でも、実際のリソースにアクセスできることがあります。書き込みをテストする前に、選択されているバインディングを確認してください。
• リモートコマンドを実行する前に、認証済みのメンバーまたは API トークンを特定し、その操作に必要な現在のロールとスコープを確認してください。ユーザーの意図を満たす範囲で、最も限定的なスコープを優先してください。wrangler login の OAuth フローは、きめ細かな認可に対応していません。きめ細かなアクセスが必要な場合は、アカウント所有の API トークンを使用し、その値をチャットに貼り付けるようユーザーに求めないでください。
• シークレットの値をコマンド引数、ソースコード、ログに含めないでください。コマンドには、ドキュメントに記載された対話式入力または保護されたファイル／stdin の仕組みを使用してください。ローカルのシークレットファイルはバージョン管理の対象外にする必要があり、デプロイ済みのシークレットとして自動アップロードされることはありません。ローカルのシークレットが見つからない場合は、ファイルの優先順位と、シークレットのドキュメントにある secrets.required の宣言を確認してください。
• wrangler secret put と secret delete はデプロイとして扱ってください。これらのコマンドはバージョンを作成し、直ちにデプロイします。変更をステージングする必要がある場合は、ドキュメントに記載された wrangler versions secret のワークフローを使用してください。
• ロールバックの前に、ロールバックの制限を確認してください。接続されたリソースとそのデータは、Worker のコードと一緒にはロールバックされません。

Workers Previews を使用する

• Workers Previews には、プロジェクトローカルの Wrangler 4.135.0 以降が必要です。プロジェクトのコマンドでは、より新しいグローバルインストールは使用されません。プロジェクトで固定されているバージョンを確認し、必要な依存関係のアップグレードを明示的に行ってください。
• 同じ Worker 上のブランチ環境やプルリクエスト環境には Previews を使用してください。本番リソースを使って特定のアップロード済みバージョンを確認するには Version URLs を使用し、永続的に個別デプロイする Worker には Wrangler environments を使用してください。古いエイリアス付き Version URL のワークフローを流用せず、ワークフローの比較に従ってください。
• まず、ユーザーが本番環境の設定とデプロイをどのように管理しているかを確認してください。Wrangler、ダッシュボード、Terraform など、本番環境と同じ設定システムで Preview ドメインを設定してください。ユーザーが別のワークフローを希望していない限り、ローカル CLI、Workers Builds、外部 CI など、既存の手順で Preview のデプロイを実行してください。本番環境のリソースバインディングやデータではなく、管理方法を合わせてください。
• デプロイする前に、最新の設定の配置表とリソースの一覧および制限事項に従ってください。ユーザーが共有を明示的に意図していない限り、Preview の名前から分離されていると推測したり、本番リソースへの書き込みを許可したりしないでください。
• アクセス制御が設定されていない限り、Preview URL は公開されることをユーザーに伝え、URL を保護するかどうかはユーザーに判断してもらってください。選択された設定に応じて、カスタムドメインとアクセスに関するガイダンスに従ってください。
• 対象とする Worker または Wrangler 環境をユーザーに確認してください。Wrangler 環境を対象にする場合は、すべての Preview コマンドに同じ --env 値を指定してください。省略すると、最上位の Worker が対象になります。

検証する

TypeScript プロジェクトで設定やバインディングを変更した後は、生成済みの宣言を手作業で編集せず、プロジェクトの wrangler types コマンドで型を再生成してください。既存の関連する型チェックまたはテストを実行してください。

デプロイの変更では、プロジェクトのビルドワークフローを使用し、対応している場合は、意図した設定と環境を指定して wrangler deploy --dry-run を実行してください。ドライランが成功すると、ビルドとパッケージングは確認できますが、リモートリソースや実行時の動作が機能することまでは証明できません。依頼された作業に応じて、適切なローカルまたはリモートの確認を行ってください。

Previews では、Wrangler が不足していると報告するバインディングに依存する動作は、URL が返されても検証できません。必要に応じて Preview 固有のログや設定を使い、ユーザーが依頼した動作を検証してください。本番リソースへの書き込み、破壊的なテスト、名前を指定した Preview の削除は、ユーザーの明示的な意図に沿って行ってください。

変更内容、対象環境、実施した確認、未解決の検証上の不足を報告してください。結果が現在のコマンドや設定の動作に依存する場合は、使用したドキュメントへのリンクを記載してください。