Cloudflare WorkersのサイトやアプリをWranglerとGitHub Actionsでデプロイしていると、新しいCLIが出るたびに「本番のパイプラインを切り替えるべきか」を判断しなければなりません。移行して動かなくなれば公開が止まり、様子見を続ければコーディングエージェントや新しいコマンドの恩恵を受けられません。新しいCLIを既存プロジェクトでうっかり実行し、設定を書き換えてしまう事故も起こり得ます。
2026年9月28日にベータになったCloudflare CLI「cf」について、公式ドキュメントと手元のサンプルプロジェクトでの検証をもとに、Wranglerとの関係、移行の手順と落とし穴、CIとエージェントでの使い方を整理し、「今どこから試すか」を編集部の提案として示します。
cfは何を置き換え、何を置き換えないのか
2026年4月に「全サービスを操作できる統一CLIを開発する」と表明された段階の話は、Cloudflareの統一CLIとクラウド選定の記事で扱いました。今回はその実物のベータ公開で、使い方と制約を文書で確認できるようになりました。
changelogによると、cfは公開されているCloudflare APIとWorkersのプロジェクトを1つのCLIで扱います。2,900を超えるコマンドがAPIをカバーし、大半は結果をJSONで出力します。インストールはnpm install -g cf、サインインはcf auth loginです。npmのcfパッケージは説明が「The Cloudflare CLI」で、2026年9月28日に1.0.0-beta.5が公開されています。
Wranglerとの違いは、公式の「cf for Wrangler users」の比較表から、判断に効く行を抜き出すと次のとおりです。
| 項目 | Wrangler | cf |
|---|---|---|
| 対象 | Workersと一部の製品 | 公開API全体（2,900超のコマンド） |
| サインイン | wrangler login | cf auth login（別の認証情報） |
| 設定ファイル | wrangler.jsonc / wrangler.toml | cloudflare.config.ts（TypeScript） |
| 環境の切り替え | envブロックと--env | モードと--mode |
| 出力 | 多くは表形式、一部に--json | 大半のAPIコマンドがJSON |
| リソースの指定 | 多くは名前 | APIが求めるID |
| ローカルとリモート | 一部はローカルが既定 | リモートが既定 |
cfは自分でバンドラーを持たず、cf devやcf buildはフレームワークのコマンド、Cloudflare Vite plugin（2.0ベータ）、またはWrangler 4.136.0以降に処理を渡します。つまりWranglerを完全に不要にするものではありません。ライブログのwrangler tailと、シークレットを1件だけ設定するwrangler secret putはcfにまだ無く、公式はnpx wranglerでの実行を案内しています。
changelogと概要・CI・移行のページには「cfはベータで、コマンド・設定・Build Outputは安定版までに変わりうる」と注記があり、安定版の時期は書かれていません。
移行しなくても使える部分：リソース操作とコマンド検索
移行しなくてもcfは使い始められます。cf d1 listやcf r2 buckets listのようなリソース・アカウント系のコマンドは、未移行のWranglerプロジェクトの中でも動きます。ただしWranglerの設定ファイルを読まないため、そこに書いたaccount_idは使われません。CLOUDFLARE_ACCOUNT_IDを設定するか、聞かれたときにアカウントを選びます。cfはWranglerのログインも再利用しないので、一度cf auth loginが必要です。
手元（Linux、Node.js 22.22.2）でcf@1.0.0-beta.5を入れ、ログインせずに試した範囲では、ドキュメントどおりの挙動でした。
cf cli search "create D1 database"
# → JSON配列で5件。先頭は "cf d1 create"、2件目は "cf d1 update"
cf dns records create --zone <ZONE_ID> --body '{"type":"A","name":"test","content":"192.0.2.1","proxied":true}' --dry-run
# → 送信するmethod・URL・bodyをJSONで表示し、何も送らずに終了
cf auth whoami
# → {"authenticated": false, "error": "Not logged in"}cf cli searchはローカルで動き、認証情報は不要です。検索語は引用符で囲みます。囲まずにcf cli search create D1 databaseとすると、Unknown commands: D1, databaseで終了コード1になりました。--dry-runも認証情報なしで使えるため、ログイン前にコマンドの形を確かめられます。
運用で注意したいのは削除です。非対話の実行（CIやスクリプト）で--forceを付けずに削除系のコマンドを実行すると、Aborted.を出して何も変えずに終了コード0で終わります。成功で終わっても削除されたとは限りません。また一部のコマンドでは--forceがAPIのパラメータも兼ね、cf workers delete --forceは他のWorkerから参照されているWorkerも削除します。
Wranglerプロジェクトで先にcf deployを実行しない
公式が繰り返し警告しているのが、移行前のWranglerプロジェクトでcf dev・cf build・cf deploy（cf init .も含む）を実行することです。これらはcloudflare.config.tsだけを読み、wrangler.jsoncは読みません。cloudflare.config.tsが無いと自動設定が走り、プロジェクトの種類によって結果が変わります。
- フレームワークも静的アセットも無いWorker：
cloudflare.config.ts is required when --experimental-new-config is enabled.で失敗 - Cloudflare Vite pluginを使うWorker：エントリポイントもバインディングも無いSPA用の設定が新たに書かれる
index.html入りの静的アセットがあるWorker：ビルドは成功するが、Workerのコードもバインディングも無い静的アセットのWorkerになる
自動設定はpackage.jsonのdeployスクリプトやロックファイル、.gitignoreも書き換え、CIでは確認なしで適用します。手元でも、フレームワークなしのWranglerサンプルでcf buildを実行すると、1つ目のエラーで終了コード1になりました（ファイルの変更はなし）。
実行してしまった場合は、git statusで変更を確認して戻し、作られたcloudflare.config.ts・wrangler.config.ts・.cloudflare/を消してからcf migrateを実行するよう公式は案内しています。
cf migrateで何が変わるか
移行はcf migrateで行います。Wranglerの設定を読み、隣にcloudflare.config.tsを書き、バインディング・ルート・トリガー・環境を変換し、cfを開発依存に加えます。Wranglerの設定ファイル自体、package.jsonのスクリプト、ソースコードは変更しません。Gitの作業ツリーに未コミットの変更があると書き込みを拒否し、既存のファイルを上書きもしません。
図のとおり、段階を分けて進めるのが公式の手順です。手元では、KVのバインディング、cronトリガー、staging環境を持つwrangler.jsoncのサンプルで、Wrangler 4.144.0を入れてから実行しました。
cf migrate --dry-run：Vite pluginが無いためWranglerのバンドラーを選んだと表示し、cloudflare.config.ts・wrangler.config.ts・package.json・package-lock.jsonの4ファイルを変更予定として列挙cf migrate：同じ4ファイルを変更。wrangler.jsoncは変わらず、環境はswitch (ctx.mode)に変換されたという[info]を表示cf buildとcf deploy --prebuilt --dry-run：ビルドは成功し、env.CACHE（KV）とenv.ENVIRONMENTを配備予定として表示して、何もアップロードせずに終了
確認できた注意点が2つあります。1つは環境の変換です。生成されたstagingの設定にはKVのバインディングが入っておらず、--mode stagingでのdry-runでもenv.ENVIRONMENTしか表示されませんでした。公式の説明どおり、Wranglerの継承規則に従ってトップレベルのバインディングやvarsは環境に写されないためです。各モードのバインディングを必ず確認します。もう1つは、package.jsonに"type": "module"が無いとビルドのたびにMODULE_TYPELESS_PACKAGE_JSONの警告が出ることで、公式の「Finish the project」に対処があります。
サンプルには含めていませんが、公式によるとDurable Objectsのmigrations、Workflows、Containersは自動変換されず、[required]の項目になります。必須項目が残る間はcloudflare.config.tsの先頭にthrowが入り、解消するまでビルドもデプロイも失敗します。Workers Sites（site）は非対応で、Workers Static Assetsへの移行が必要です。WranglerのバンドラーのままでもWrangler 4.136.0以降が要ります。また、Astro 6以降はベータの間cfでビルドできないとドキュメントにあります。
CIとエージェントに入れるときの設定
CI：トークン、バージョン固定、モードの一致
CIではcf auth loginが使えないため、CLOUDFLARE_API_TOKENとCLOUDFLARE_ACCOUNT_IDをシークレットに入れます。トークンは保存済みのログインより優先され、アカウントが複数見えるのに指定が無いと、確認を求めずに失敗します。cfはグローバルではなく開発依存に入れ、npx cfでプロジェクトのバージョンを使います。Node.jsは22.18以降が必要で、Bunは非対応です。テレメトリーはCF_SEND_TELEMETRY=falseかDO_NOT_TRACK=1で止められます。
公式のGitHub Actionsの例は、cf buildを1回だけ実行し、PRではcf deploy --prebuilt --mode production --dry-run、mainへのpushでだけ同じビルドを本番に配備する構成です。dry-runは認証情報が不要なので、フォークからのPRでも動きます。
手元の検証で引っかかったのがモードです。この例はcf initで作ったVite構成を前提にしています。Viteのビルドはモードを必ず記録しますが、Wranglerのバンドラーで移行したプロジェクトは、cf buildに--modeを渡したときだけ記録します。実際に、--modeなしでビルドしてからcf deploy --prebuilt --mode production --dry-runを実行すると、「Build Outputにモードが記録されていない」というエラーで止まりました。移行したプロジェクトに公式の例を写すときは、ビルドとデプロイで--modeの有無をそろえます。
エージェント：指示の1行と、触らせない操作
公式は、ユーザー単位のAGENTS.mdやCLAUDE.mdに「Cloudflareを操作するときはcfを使う。ただしWranglerの設定ファイルがあるプロジェクトは除く」という指示を足すよう勧めています。Claude Codeでどちらのファイルが読まれるかは、AGENTS.mdが読まれない条件の記事で確認できます。
cf --helpの先頭には、エージェントにcf cli searchから始めるよう促す案内が出ます。手元のbeta.5では、検索語に名前・メールアドレス・ドメイン・アカウントやリソースのID・トークンを含めないという指示も表示されました。エージェントがcf dev・cf build・cf deployを未移行のWranglerプロジェクトで実行しないよう、公式は注意を促しています。人がいない環境のエージェントはCLOUDFLARE_API_TOKENで認証し、手元で案件ごとに認証情報を分けるには名前付きプロファイル（cf auth create・cf auth activate）を使います。
今すぐ移すか、待つか
ここからは、上記の公式仕様と手元の検証を踏まえた編集部の提案です。
| 状況 | 提案 |
|---|---|
| 本番のデプロイがWranglerで安定している | デプロイは切り替えない。リソース確認やcf cli searchを手元とエージェントで試す |
| Durable Objects、Workflows、Containers、Workers Sitesを使う | 移行は後回し。手作業の変換が必要。Durable Objectsのクラスの作成・削除・改名は、変更前のバージョンにロールバックできない |
wrangler tailやwrangler secret putを日常的に使う | Wranglerの設定を残したまま併用する前提で計画する |
| 新規の小さなWorker、または検証用のブランチを切れる | cf migrate --dry-runから始め、cf buildとcf deploy --dry-runをCIのPRで回す |
いずれの場合も、最初にやっておきたいのは次の2つです。
- CIの設定やエージェントの指示で、Wranglerプロジェクトに対して
cf dev・cf build・cf deployが実行されないようにする - 移行を試すブランチで
cf migrate --dry-runを実行し、[required]の項目と、モードごとのバインディングを確認する
ベータの間はコマンド・設定・Build Outputが変わりうるため、本番のデプロイを切り替えるのは、dry-runをCIで一定期間回し、安定版の告知を確認してからでも遅くありません。PRごとの確認環境まで視野に入れるなら、Worker Previewsの記事で整理した本番データとの共有範囲も合わせて確認しておきます。
2026年9月30日に、Cloudflareのchangelog（2026年9月28日の項）と、cfのドキュメント（概要、Coding agents、CI、環境変数、Get started、Workers projects、Coming from Wrangler）を、公式ドキュメントのソースリポジトリ（2026年9月29日のコミット）で直接読んで照合しました。npmの
cfパッケージの公開版・日付はregistryで確認しました。実機ではLinux・Node.js 22.22.2でcf@1.0.0-beta.5とWrangler 4.144.0を使い、ヘルプ表示、コマンド検索、dry-run、サンプルプロジェクトでのcf migrate・cf build・cf deploy --dry-runまでを確認しました。Cloudflareアカウントへのログイン、実際のデプロイ、GitHub Actionsでの実行、Durable Objects・Vite構成の移行は実施していません。
Workersの運用やCI、コーディングエージェントを使った開発・自動化の進め方は、グリームハブへご相談ください。
Sources
- Cloudflare CLI is now in beta — Cloudflare Changelog
- Cloudflare CLI — Cloudflare Docs
- cf for Wrangler users — Cloudflare Docs
- Migrate a Wrangler project — Cloudflare Docs
- Wrangler to cf reference — Cloudflare Docs
- Use cf in CI — Cloudflare Docs
- Use cf with coding agents — Cloudflare Docs
- Get started — Cloudflare Docs
- Deploy your first Worker — Cloudflare Docs
- Develop, build, and deploy — Cloudflare Docs
- Environment variables — Cloudflare Docs
- cf — npm registry
