Cloudflareの新しいcf CLI実践ガイド

cfは、Cloudflare API全体を扱えるCloudflare公式のコマンドラインツールです。2026年9月28日にオープンベータとして公開され、Node.js 22.18以降の環境でnpm i -g cfを実行するとインストールできます。

Wranglerを使ってWorkersをデプロイしている方は、Wranglerが対応していないDNS、ゾーン、各種設定のためにダッシュボードを開いているのではないでしょうか。cfは、アカウントのリソースとWorkerプロジェクトの両方を1つのバイナリで扱えます。本ガイドでは、インストール、出力の読み方、新しいTypeScript設定ファイルの書き方、デプロイ、既存Workerの移行までを順に解説します。Workersの基本を復習したい場合は、まずこちらのCloudflare Workers入門ガイドをご覧ください。

cfはWranglerとどう違うのか

Wranglerはコマンドを1つずつ追加しながら成長してきたCLIです。cfはこれを置き換えるもので、CloudflareのOpenAPIスキーマから生成されています。ローンチ発表によると、Wranglerが約280のAPIオペレーションに対応しているのに対し、cfは3,000を超えるオペレーションに対応しています。cfのドキュメントでは数え方が異なり、2,900以上のコマンドとされています。cfはコーディングエージェントでの利用を念頭に設計されていますが、人が手で入力してもすべてのコマンドが同じように動作します。

変更履歴のエントリでは、安定版リリースまでにコマンド、設定、Build Outputが変更される可能性があると注意喚起されています。

cfのインストールとログイン

npmからcfパッケージをインストールし、cf auth loginで認証します。cfという名前のコマンドをインストールするツールはほかにもあるため、cloudflare/cfリポジトリにリンクしている公式パッケージであることを必ず確認してください。

npm i -g cf
cf --version

cf auth login     # add --no-browser over SSH or in a container
cf auth whoami

Get startedドキュメントによると、このパッケージは同じCLIをcfとcloudflareという2つの名前で提供します。PATH上のほかのコマンドがすでにcfという名前を使っている場合は、代わりにcloudflareとして呼び出してください。ログイン時には、cfがリンクとワンタイムコードを表示し、そのリンクをブラウザで開くので、そこで承認します。cfは独自に認証情報を保存するため、Wranglerのログイン状態は引き継がれません。

CI環境では、代わりにCLOUDFLARE_API_TOKENとCLOUDFLARE_ACCOUNT_IDを設定します。この方法で設定したトークンは、保存済みのログインよりも優先されます。

まずは読み取り専用のコマンドから試してみましょう。

cf zones list

cfのJSON出力を読み取り、フィルタリングする

ほとんどのcfコマンドは結果をJSONとしてstdoutに書き出し、進行状況やステータスメッセージはstderrに出力します。そのため、追加のフラグなしで結果をファイルに保存したり、jqにパイプしたりできます。

cf zones list > zones.json        # results only; status stays on stderr
cf zones list | jq .              # inspect the shape
cf zones list | jq '.[].id'       # print each zone's id
cf zones list --name example.com  # look up one domain

リソース管理のドキュメントにあるとおり、cf zones listはJSON配列を返し、各ゾーンにはidフィールドがあります。ゾーン内で操作するコマンドは--zoneまたはその短縮形-zを受け付け、ゾーンIDとドメイン名のどちらでも指定できます。

cf dns records list --zone example.com
cf dns records list -z example.com

cf cli searchでコマンドを探す

目的のコマンドを探すには、やりたいことを自然な言葉で記述してcf cli searchを実行し、提案されたコマンドのヘルプを開きます。エージェント向けドキュメントによると、cf cli searchは最大5件の候補を、最も一致度の高いものから順にJSON配列として返します。検索はローカルマシン上で行われるため、ログインしている必要はありません。

cf cli search "create a DNS record"
cf dns --help
cf complete zsh >> ~/.zshrc   # shell completion

--helpはコマンドツリーのどの階層でも使用できます。

cloudflare.config.tsでWorkersを設定する

cloudflare.config.tsは、cfでWorkersを設定するためのTypeScript設定ファイルです。cf/configからdefineConfigをインポートし、その結果をdefault exportします。バインディングやトリガーは型付きのヘルパーで宣言するため、エディターの補完が効きます。プログラマティック設定のリファレンスにあるとおり、このファイルは通常のTypeScriptモジュールなので、インポート、関数、環境変数、非同期の値も使用できます。

ローンチ記事の最初の例では、with { type: "cf-worker" }インポート属性を付けてWorkerモジュールをインポートし、name、entrypoint、compatibilityDateを設定しています。以下の抜粋では、これらのフィールドを// ...で省略しています。次の抜粋は、ローンチ記事のbindingsの例を簡略化したもので、modeによって値を切り替えられるよう、defineConfigに関数を渡しています。

import { bindings, defineConfig } from "cf/config";

export default defineConfig(({ mode }) => ({
  worker: {
    // ...
    env: {
      API_TOKEN: bindings.secret(),
      DATABASE: bindings.d1({ name: `example-${mode}-database` }),
      UPLOADS: bindings.r2({ name: `example-${mode}-uploads` }),
      JOBS: bindings.queue<{ userId: string }>({
        name: `example-${mode}-jobs`,
      }),
      AI: bindings.ai(),
    },
  },
}));

完全版の例では、bindings.text、bindings.kv、bindings.vectorize、bindings.workerも使われています。トリガーは1つの配列にまとめて記述します。次の抜粋では、defineConfigにプレーンなオブジェクトを渡しています。

import { defineConfig, triggers } from "cf/config";

export default defineConfig({
  worker: {
    // ...
    triggers: [
      triggers.fetch({ pattern: "example.com/*" }),
      triggers.scheduled({ schedule: "0 * * * *" }),
      triggers.queue({ name: "jobs", maxBatchSize: 10 }),
    ],
  },
});

ローンチ記事の例にはtriggers.emailのエントリも追加されています。リファレンスには、rawソケットを扱うtriggers.connectも記載されています。Cloudflareはローンチ記事の中で、将来的にこのファイルでゾーンやDNSも設定できるようにする予定だと述べています。現時点では、default exportで扱えるのはWorker、Containerアプリケーション、アカウント設定です。

Init、Deploy、Migrate

新規プロジェクトにはcf init、リリースにはcf deploy、既存のWranglerプロジェクトにはcf migrateを使用します。

cf init my-worker      # or `cf init .` inside an existing app
cf deploy

cf initはcloudflare.config.tsとvite.config.tsを作成し、既存のViteアプリでは@cloudflare/vite-pluginをインストールします。引数なしで実行すると、処理を止めてディレクトリの指定を求めます。デプロイのドキュメントによると、cf deployを1回実行するだけで、プロジェクトのビルドとチェック、使用する認証情報とアカウントの判定、新しいWorker Versionのアップロードと公開までが行われます。静的サイトであれば、最初のcf deployの前に設定ファイルを用意する必要はありません。

プロジェクトにwrangler.toml、wrangler.json、wrangler.jsoncのいずれかがある場合は、cf dev、cf build、cf deployを実行する前に移行してください。これら3つのコマンドはcloudflare.config.tsのみを参照し、Wranglerの設定ファイルは無視します。

cf migrate --dry-run
cf migrate

cf migrateはTOMLを直接読み込めるため、古いファイルを事前に変換する必要はありません。既存のwrangler.tomlをJSON形式で確認したいだけであれば、TOML to JSONコンバーターを利用できます。「cf for Wrangler users」ガイドによると、プロジェクトがすでにCloudflare Viteプラグインを使用している場合を除き、移行後もWranglerのバンドラーが引き続き使用されるため、Viteへの切り替えは任意です。Wranglerのバンドラーを維持する場合はwrangler.config.tsが生成され、移行ドキュメントによると、Workerのパッケージには Wrangler 4.136.0以降がインストールされている必要があります。ローンチ記事では、RustおよびPythonのWorkersも引き続きWranglerに処理を委譲すると補足されています。

Wranglerは今後どうなるのか

Wranglerは当面引き続き動作しますが、終了の方針はすでに決まっています。cfのオープンベータ終了後、CloudflareはユーザーをcfへとWranglerの最終メジャーバージョンをリリースし、その時点から18か月間Wranglerのメンテナンスを続ける予定です。ベータの終了時期はまだ発表されていないため、この18か月の具体的な期日も決まっていません。

Viteがデフォルトのビルドツールになったことは、Workersエコシステム全体でViteへの移行が進んでいる流れとも一致しています。

まとめ

cfはWranglerと併用してインストールできます。リソース関連のコマンドは未移行のプロジェクトでも動作し、切り替えが問題になるのはWorkerのビルドをcfに移すときだけです。公式パッケージをインストールしたら、cf zones list | jq .を実行して出力を実際に確認してみてください。そして、ベータが終了してWranglerのメンテナンス期間が始まる前に、重要度の低いWorkerのブランチでcf migrate --dry-runを試しておくことをおすすめします。

よくある質問

複数のCloudflareアカウントでcfを使うにはどうすればよいですか?

名前付きプロファイルを使用します。cf auth create workを実行してプロファイルを作成してサインインし、続いてcf auth activate workを実行すると、そのプロファイルが現在のフォルダーとその配下のすべてのフォルダーに紐付けられます。1つのコマンドだけで特定のプロファイルを使う場合は--profile workを指定し、すべてのプロファイルを確認するにはcf auth listを実行します。CLOUDFLARE_API_TOKEN環境変数はすべてのプロファイルより優先され、設定されている間はプロファイル管理コマンドが使用できなくなります。

cfは.envファイルから認証情報を読み込めますか?

はい。APIコマンドは、実行したフォルダーにある.envファイルからCLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_ZONE_IDを読み込めます。cfが参照するのは.envのみで、.env.localは参照しません。.envが.gitignoreに含まれていることを必ず確認してください。この方法で読み込まれたトークンは、どのプロファイルや保存済みログインよりも優先されます。cfはGlobal API Keyをサポートしていないため、代わりにスコープを限定したAPIトークンを使用してください。

モノレポ内のWranglerプロジェクトを移行するにはどうすればよいですか?

cf migrateに設定ファイルのパスを渡します。たとえばcf migrate packages/api/wrangler.jsonc --dry-runを実行し、続いて--dry-runを外して同じコマンドを実行します。パスを指定しない場合、cf migrateはカレントディレクトリにwrangler.json、wrangler.jsonc、wrangler.tomlのいずれかがちょうど1つ存在することを前提とします。生成されるファイルは設定ファイルと同じ場所に書き出されます。バンドラーは--bundler viteまたは--bundler wranglerを指定しない限りpackage.jsonから判断されます。また、Gitのワークツリーがクリーンでない場合は--forceが必要です。

移行前のWranglerプロジェクトでcf deployを実行するとどうなりますか?

cfはwrangler.jsoncやwrangler.tomlを無視するため、独自にプロジェクトをセットアップし、package.jsonなどのファイルを変更してしまう可能性があります。元に戻すには、git statusを実行して変更されたファイルをそれぞれgit restoreで復元し、cloudflare.config.ts、wrangler.config.ts、.cloudflareディレクトリなどの新規作成されたファイルを削除します。そのうえでcf migrateを実行してください。なお、cf migrateはcloudflare.config.tsが存在する間は実行されません。