Wrangler CLI

本ファイルは cloudflare/skills（Apache-2.0）を基に改変しています。詳細は リポジトリルートの ATTRIBUTION.md を参照。

原則: 仕様の確認と調査は MCP、deploy / secret put / d1 migrations apply は監査性・可逆性・秘密保護のため wrangler CLI を既定にする(MCP に能力が無いからではない)。操作別の既定表と MCP 不通時の復旧は references/mcp-vs-cli-routing.md が唯一の正本。

Wrangler の CLI フラグ・設定フィールド・サブコマンドに関する知識は古くなっている可能性がある。事前学習した知識より取得 (retrieval) を優先すること。

最初に: package managerとWranglerを確認する

既存projectではlockfileを正本にし、package managerを勝手に移行しない。

検出したlockfile	Wrangler command
pnpm-lock.yaml / pnpm-workspace.yaml	pnpm exec wrangler
package-lock.json / npm-shrinkwrap.json	npx --no-install wrangler
yarn.lock	yarn exec wrangler

新規AIDD projectでlockfileがまだない場合だけpnpmを既定にする。以下の例は、このrepositoryの既定であるpnpm exec wranglerで表記する。npm/yarn projectでは上表のprefixへ置き換え、subcommandとflagsは同じに保つ。

pnpm exec wrangler --version   # v4.x 以上が必要

未インストールなら:

pnpm add -D wrangler@latest

既存lockfileがない新規AIDD projectはpnpmへ統一する。既存npm/yarn projectへpnpm lockfileを追加しない。可能な限りAPI requestを手で組み立てず、project-localなWranglerを使う。

You installed workerd on another platform、workerd-darwin-64、workerd-darwin-arm64が出た場合、別PCのnode_modulesやlockfile削除で回避しない。pnpm-workspace.yamlのsupportedArchitecturesを確認してから次を実行する。

pnpm install --force --frozen-lockfile
pnpm exec wrangler --version

複数Accountの安全規則

Cloudflareへ変更を加えるコマンドの前に、選択したpackage managerのwrangler whoamiで対象Accountを確認する。このrepositoryではpnpm exec wrangler whoamiを使う。チーム用共有Accountと個人Accountの両方があり、新しく自社アプリを作る場合はチーム用Accountを既定選択する。個人Accountは利用者の明示指定時だけ。

既存wrangler.jsoncやWorker/D1/R2が特定Accountにある場合は、その所有先を優先して照合する。チームへ移したい場合も別Accountへ同名リソースを勝手に作らず、移行タスクとして止める。Account不一致時はcreate / secret put / migrations apply / deployを実行しない。

最新情報の取得先

コマンドや設定を書く・レビューする前に最新の情報を取得する。CLI フラグ、設定フィールド、バインディング形状を記憶に頼って書かない。

ソース	取得方法	用途
Wrangler docs	https://developers.cloudflare.com/workers/wrangler/	CLI コマンド、フラグ、設定リファレンス
Wrangler 設定スキーマ	node_modules/wrangler/config-schema.json	設定フィールド、バインディング形状、許可値
Cloudflare docs	検索ツール または https://developers.cloudflare.com/workers/	API リファレンス、compatibility date/flag

主要原則

• wrangler.jsonc を使う: TOML より JSON を優先。新機能は JSON 専用のものがある。バージョン管理し、Worker 設定の唯一の情報源として扱う。
• compatibility_date を設定する: 直近 30 日以内の日付を使い、四半期ごとに更新する。
• 設定変更後は pnpm exec wrangler types: TypeScript バインディングを再生成する。CI のビルドステップにも入れてバインディング不一致を検出する。
• ローカル開発はデフォルトでローカルストレージ: バインディングは remote: true を指定しない限りローカルシミュレーション。
• 環境で staging/production を分ける: env.staging / env.production を設定に定義する。
• ローカルで先にテストする: デプロイ前に pnpm exec wrangler dev で確認し、大きな変更前は pnpm exec wrangler deploy --dry-run で検証する。
• 自動プロビジョニングを使う: リソース ID を省略するとデプロイ時に自動作成される。

落とし穴 (gotchas)

• シークレットをコマンドに埋め込まない: 値を CLI 引数で渡す、echo でパイプする、ログ出力する、ハードコードする — いずれも禁止。対話プロンプト (pnpm exec wrangler secret put)、ファイル入力 (< key.pem、secret bulk)、CI の安全な環境変数を使う。ローカル用シークレットは .dev.vars に置き、設定ファイルにはコミットしない。
• secret putの前にsecret list: 同名があれば新規設定ではなくローテーション。既存ログインの無効化や全セッション失効を説明し、明示承認なしに上書きしない。
• D1 の --remote / --local を明示する: 取り違えると本番データを操作する事故になる。
• Workers AI は常にリモート実行: ローカル開発中でも利用料金が発生する。バインディングには remote: true が必要。
• リモート推奨のバインディング: AI (必須)、Vectorize、Browser Rendering、mTLS、Images。
• バインディングが undefined: バインディング名が設定と完全一致しているか確認する。
• 起動時間の上限超過: pnpm exec wrangler check startup でプロファイルを取る。
• レジストリ認証情報をハードコードしない: 環境変数経由で渡す (Containers)。
• Hyperdrive のパスワード・接続文字列も環境変数経由にする。

頻出コマンド早見表

やりたいこと	コマンド
ローカル開発サーバー起動	pnpm exec wrangler dev
デプロイ	pnpm exec wrangler deploy
デプロイのドライラン	pnpm exec wrangler deploy --dry-run
TypeScript 型を生成	pnpm exec wrangler types
起動時間をプロファイル	pnpm exec wrangler check startup
ライブログを見る	pnpm exec wrangler tail
直前バージョンへロールバック	pnpm exec wrangler rollback
シークレットを設定	pnpm exec wrangler secret put API_KEY
D1 マイグレーション適用 (本番)	pnpm exec wrangler d1 migrations apply my-db --remote
Worker を削除	pnpm exec wrangler delete
認証状態の確認	pnpm exec wrangler whoami
新規プロジェクト作成	pnpm exec wrangler init my-worker / pnpm create cloudflare@latest my-app

サービス別の頻出コマンド

# D1
pnpm exec wrangler d1 create my-db
pnpm exec wrangler d1 execute my-db --local  --command "SELECT * FROM users"
pnpm exec wrangler d1 execute my-db --remote --file ./schema.sql
pnpm exec wrangler d1 migrations create my-db create_users_table
pnpm exec wrangler d1 migrations apply my-db --local

# KV
pnpm exec wrangler kv namespace create MY_KV
pnpm exec wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600
pnpm exec wrangler kv key get --namespace-id <ID> "key"

# R2
pnpm exec wrangler r2 bucket create my-bucket
pnpm exec wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt

# シークレット (値は対話プロンプトかファイルで渡す)
pnpm exec wrangler secret put API_KEY
pnpm exec wrangler secret put PRIVATE_KEY < path/to/private-key.pem
pnpm exec wrangler secret list

# ログ
pnpm exec wrangler tail --status error
pnpm exec wrangler tail --search "error" --format json

# 環境を指定した実行/デプロイ
pnpm exec wrangler dev    --env staging
pnpm exec wrangler deploy --env staging

# cron ハンドラのローカルテスト
pnpm exec wrangler dev --test-scheduled   # → http://localhost:8787/__scheduled

よく使うバインディング設定

{
  "vars": { "ENVIRONMENT": "production" },
  "kv_namespaces": [{ "binding": "KV", "id": "<KV_NAMESPACE_ID>" }],
  "r2_buckets":    [{ "binding": "BUCKET", "bucket_name": "my-bucket" }],
  "d1_databases":  [
    { "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>",
      "migrations_dir": "./migrations" }
  ],
  "ai": { "binding": "AI" },
  "vectorize":  [{ "binding": "VECTOR_INDEX", "index_name": "my-index" }],
  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }],
  "durable_objects": {
    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
  },
  "queues": {
    "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }],
    "consumers": [{ "queue": "my-queue", "max_batch_size": 10 }]
  },
  "workflows": [
    { "binding": "MY_WORKFLOW", "name": "my-workflow", "class_name": "MyWorkflow" }
  ],
  "triggers": { "crons": ["0 * * * *"] },
  "observability": { "enabled": true, "head_sampling_rate": 1 },
  "env": {
    "staging": { "name": "my-worker-staging", "vars": { "ENVIRONMENT": "staging" } }
  }
}

Pipelines / Secrets Store / Containers のバインディング形状は各リファレンスを参照。

トラブルシュート早見表

問題	対処
command not found: wrangler	pnpm add -D wrangler@latest
認証エラー	pnpm exec wrangler login
workerdのplatform/CPU不一致	supportedArchitectures確認後にpnpm install --force --frozen-lockfile
複数Accountで対象が不明	既存リソース所有先を照合。新規ならチーム用Account、個人は明示指定時だけ
起動時間の上限超過	pnpm exec wrangler check startup でプロファイル
設定変更後の型エラー	pnpm exec wrangler types
ローカル状態が消える	.wrangler/state を確認
バインディングが undefined	設定のバインディング名と完全一致しているか確認

詳細リファレンス

必要になったときに該当ファイルを読むこと。

状況	読むファイル
wrangler.jsonc を書く・バインディングを追加する・型生成をする	references/config.md
ローカル開発、リモートバインディング、.dev.vars、Vitest / scheduled のテスト	references/dev-local.md
デプロイ、バージョン管理とロールバック、Pages、認証	references/deploy.md
Worker シークレット、Secrets Store の操作	references/secrets.md
D1 のデータベース作成、SQL 実行、マイグレーション、エクスポート	references/d1.md
KV Namespace / キー操作、R2 バケット / オブジェクト操作	references/kv-r2.md
Workers AI のモデル一覧、Vectorize のインデックス、Hyperdrive の設定	references/ai-vectorize-hyperdrive.md
Queues、Workflows とそのインスタンス、Pipelines	references/queues-workflows-pipelines.md
コンテナイメージのビルド/プッシュ、外部レジストリ設定	references/containers.md
ログの tail、observability 設定、エラーの切り分け	references/observability-troubleshooting.md

最小構成のスターター

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01"
}

バインディングを含むフル構成の例は references/config.md にある。