メインコンテンツへスキップ
見出し画像

Cloudflareの新CLI「cf」は本当に全API対応か ─ npmパッケージの中身を数えて、Terraformとの線引きを考えた

    「Cloudflare、全APIに対応しTypeScriptで設定可能な新コマンドラインツール『cf』をリリース」。gihyo.jp のこの見出しを見て、最初に思ったのは「全部って、本当に?」だった。

    Cloudflare の設定は、これまで Terraform で書いてきた。書ける範囲は書けるのだが、どうにも中途半端さが残る。コードで持つ設定と、結局ダッシュボードで触る設定が混ざる。provider のメジャーアップデートのたびに、移行の段取りで手が止まる。

    なので今回は調べる側に回った。実機で運用を回したわけではない。公式ブログ3本と README、changelog を読み、npm から `cf` パッケージを落として同梱のコマンド定義を数えた。

    先に結論を書いておく。「全API対応」はおおむね本当だ。ただしそれは「公開 OpenAPI に載っている約2,900の操作を、CLI から1つずつ叩ける」という意味だった。Terraform で中途半端だった「宣言的に全部を管理する」が解決したわけではない。

    発表の中身

    cf の発表は2026年9月28日(米国時間)。ステータスは open beta で、npm の latest は 1.0.0-beta.5。Node.js 22 以上が要る。ライセンスは MIT OR Apache-2.0 のデュアルで、リポジトリは github.com/cloudflare/cf にある。

    npm i -g cf

    2026年4月13日には Technical Preview として `npx cf` が公開済みで、今回はそのオープンベータ版にあたる。

    コマンドの大半は、同日に発表された Forge という生成パイプラインで作られている。OpenAPI スキーマに少し注釈を足したものを入力に、CLI を生成する仕組みだ。Forge も Apache 2.0 で OSS 化された。ブログは規模をこう書いている。

    "expand cf from the ~280 functions that Wrangler had built up over time, to cover the entirety of the Cloudflare API surface of over 3,000 operations."

    自分の訳だと「Wrangler が積み上げてきた約280の機能から、3,000超のオペレーションからなる API の面全体へと cf を広げる」。見出しの「全API」はここから来ている。

    公式の数字は3種類、実物は2,936だった

    気になったのは、公式の数字が文書ごとに揺れていることだ。cf の発表ブログは "over 3,000"。同じ日の Forge のブログは "over 3,500"。4月のブログは "nearly 3,000" だった。

    そこで 1.0.0-beta.5 に同梱の `dist/_meta/commands.json` を集計した。コマンドの総数は2,936。API から生成されたものが2,889、手書きが47だった。

    トップレベルのグループは163ある。多い順に zero-trust が382、cloudforce-one が219、radar が152、magic-transit が138。メソッド別では GET 1,381、POST 625、DELETE 376、PUT 283、PATCH 224 で、半分近くが読み取り系だ。

    ヘルプ一覧に出ない hidden 扱いも950件あるが、自然言語でコマンドを探す `cf cli search` の検索対象には入っている。

    公式の数字と実物の差の内訳までは確認できなかった。ただ、理由の一部は changelog に書いてある。`x-fern-audiences` で cf-cli 向けでないと宣言された操作は、生成時に除外する。成功レスポンスを宣言していない hidden な操作も無視する。

    画像

    入っていないもの、手で補っているもの

    README は出どころをはっきり書いている。

    "generated from Cloudflare's public OpenAPI surface"

    「Cloudflare の公開 OpenAPI の面から生成された」(自分の訳)。公開スキーマに無いものは、原理的に生成されない。

    たとえば GraphQL Analytics API(`/graphql`)のコマンドは、同梱メタデータに見当たらなかった。Forge のブログも、今の入力は OpenAPI だけで GraphQL などは将来の設計だとしている。`wrangler tail` に相当するログ tail も、生成コマンドの中には見当たらなかった。

    逆に、OpenAPI だけでは足りない部分は手書きで補っている。Access、cloudflared 経由の Tunnels、Containers の build/push/ssh、D1 migrations あたりだ。deploy/dev/init/migrate、auth、ドメイン登録も手書きになっている。

    README にはこうもある。

    "it changes with the pinned public OpenAPI release."

    意味は「固定された公開 OpenAPI のリリースに合わせて変わる」(自分の訳)。API 仕様の更新で、コマンドの形が変わりうる。実際 beta の途中で、`cf tunnel` が `cf tunnels` に改名されている。スクリプトに埋め込むなら、バージョンは固定したほうがいい。

    画像

    TypeScript で書けるのは、今のところ Worker だけ

    見出しのもう半分も確かめた。設定ファイルは `cloudflare.config.ts` で、`cf/config` から `defineConfig` などを読み込む。ブログの例はこんな形だ。

    import { defineConfig, triggers } from "cf/config";
    export default defineConfig({
      worker: {
        // ...
        triggers: [
          triggers.fetch({ pattern: "example.com/*" }),
          triggers.scheduled({ schedule: "0 * * * *" }),
        ],
      },
    });

    書いているのは Worker の設定だ。型定義の `@cloudflare/config` 0.20.0 を見ると、トップレベルのキーは4つしかない。`worker`、`containers`、`accountId`、`complianceRegion`。DNS もゾーンも WAF も、キー自体が存在しない。ブログは将来についてこう書く。

    "Soon you will be able to configure entire policies, set up zones, configure DNS and more, all through this configuration file."

    自分の訳では「近いうちに、ポリシー全体の設定、ゾーンの作成、DNS の設定などを、すべてこの設定ファイルからできるようになる」。裏を返せば、今はまだできない。`@cloudflare/config` 自身も説明文に "not yet stable enough for external use" と書いている。

    画像

    plan も state も無い、命令型の CLI

    ここが一番大事なところだと思う。cf は、1つの API 操作を1つのコマンドとして叩く命令型の CLI だ。あるべき状態を書き、差分を plan で見て、apply で寄せる Terraform とは発想が違う。

    公式ブログ、README、changelog、コマンド一覧のどこにも、plan や state、ドリフト検出に当たる機能は見つからなかった。既存リソースを取り込む import も無い(`cf dns records import` は DNS の API 機能で別物)。

    変更前の確認手段はある。生成コマンドには `--dry-run` がある。説明は "Validate and show what would happen without executing"。DELETE と破壊的と注釈された操作では確認プロンプトが出て、`--force` で省略できる。

    ただ、これは1コマンド単位の確認だ。「本番の DNS やルールが、全体としてあるべき姿か」に答えてくれる道具ではない。

    画像

    Terraform 側で起きていたこと

    自分が感じていた中途半端さは、自分だけのものではなかった。

    2024年9月24日、Cloudflare は provider v5 の alpha を出し、OpenAPI からの自動生成に切り替えた。旧方式では、新しいエンドポイント1つに最低3本の PR が要り、網羅が遅れていたという。2025年2月3日の v5 GA では "100% API property support" を掲げた。一方で、作り直しなので一部に破壊的変更がある、とも明記していた。

    その後の issue を読むと、網羅と安定の溝が見える。Issue #5573 では、`cloudflare_ruleset` を個別ルール単位で管理できないことが挙がっていた。v4 からの state 移行の不足や、apply のたびに差分が出る回帰も並ぶ。エンタープライズ利用者の強い不満も書き込まれている。

    Issue #5044 では、DNS レコードのリソース移行ツールが不完全だった。利用者が state の JSON を手で直す回避策を共有している。安定化リストの Issue #6237 では、安定化済みは99リソース。メンテナは「大半の利用者はこのリストの1/4も使っていないので、全部の完了を待たないで」と答えている。

    つまり Terraform も、自動生成で API の網羅はいったん達成した。難しかったのは、それを宣言的な管理として安定させるほうだ。cf は同じ網羅を命令型 CLI という別のやり方で実現したもので、Terraform の安定性の問題を直接片づけるものではない。

    今後について、cf のブログに Terraform の言及は無かった。Forge のブログにだけ、こうある。

    "We'll have more on our SDKs very soon, including TypeScript, Rust, Python, Go, PHP, and Terraform. Especially Terraform."

    自分の訳で「SDK については近いうちにもっと話せることがある。TypeScript、Rust、Python、Go、PHP、そして Terraform。とくに Terraform」。cf が Terraform を置き換えるのか並んで続くのかは、公式からは明言されていない。

    「パッケージ40%削減」は設定ファイルの話

    gihyo の記事には「cfのパッケージ自体のサイズがWranglerより約40%削減されたという」という一文がある。原文と読み比べると、ここは別の話だった。

    "Some Wrangler configuration files inside Cloudflare have been condensed by 40% from over 5,000 lines, with many custom environments per developer, to factory files that build each developer's configuration more efficiently."

    自分の訳では「Cloudflare 社内の Wrangler 設定ファイルの一部は、開発者ごとに多くのカスタム環境を抱えて5,000行を超えていた。それが、各開発者の設定をより効率よく組み立てるファクトリーファイルにすることで40%圧縮された」。40%は社内の設定ファイルの話で、パッケージのサイズではない。

    念のため npm の展開後サイズも見た。cf 1.0.0-beta.5 が約23.3MB、wrangler 4.143.0 が約15.4MB。依存の抱え方が違うので単純比較はできないが、「パッケージが40%小さい」を裏づけるデータは見当たらなかった。

    セキュリティ運用の目で気になったところ

    まずテレメトリが既定で有効なこと。telemetry.md によれば、`cf cli search` の検索クエリやセッション ID のハッシュなどを送る。検出したコーディングエージェントの種類も含まれる。止めるには `cf cli telemetry disable` か `DO_NOT_TRACK=1`。社内や CI に入れるなら、最初に切っておきたい。

    `--help` の冒頭にはエージェント向けの案内が出て、こんな一文がある。

    "Keep cf cli search queries anonymous; describe the action and resource type only."

    訳すと「cf cli search のクエリは匿名に保ち、操作とリソースの種類だけを書くこと」(自分の訳)。クエリが外に出る前提で、固有名を入れるなと言い含めているわけだ。

    認証は環境変数 `CLOUDFLARE_API_TOKEN` が最優先で、次に OAuth のプロファイル。`cf auth login` は device flow が既定で、`--scopes` でスコープを絞れる。プロファイルはディレクトリに紐づけられるので、場所によって権限が変わることは意識しておきたい。

    `--local` で KV や D1、R2 の一部をローカルで試せる。ローカルに対応が無いコマンドは、本番に落ちずにエラーを返すと README にある。

    名前の衝突もある。HN のコメントでは、Cloud Foundry の CLI も `cf` なのでぶつかる、という声があった。bin には `cloudflare` という別名もあるので、スクリプトではそちらを使うのも手だ。

    当面はこう使い分ける

    調べた範囲での、自分の使い分けはこうだ。

    本番の「あるべき状態」の管理は、当面 Terraform(v5)を続ける。DNS、WAF の ruleset、Zero Trust のポリシーあたりだ。cf には state も plan も無いので、差分を見て寄せる仕事は任せられない。

    棚卸しや調査、Terraform で書けない穴の穴埋め、単発の一括操作は cf の出番だと思う。GET だけで1,381コマンドあり、現状確認の道具としてはかなり強い。変更をかけるときは `--dry-run` を先に通し、API トークンのスコープは必要な分に絞る。

    Workers の開発は、cf と `cloudflare.config.ts` への移行を検討していい。ただし beta で、設定パッケージは自分で「まだ安定していない」と書いている。Wrangler は beta 終了後も18か月メンテナンスが続くと公式が書いている。beta の終了日はまだ発表されていないので、急ぐ理由は今のところ無い。

    エージェントに cf を渡すなら、次は決めておきたい。

    • 調査用途なら読み取り専用のトークンを渡す

    • テレメトリを切っておく

    • `--force` はエージェントに使わせない

    • cf のバージョンを固定する

    ブログによれば、Wrangler 利用に占めるエージェントの割合は2026年3月に4分の1、発表の前週には48%だった。渡す前提で備えておいたほうがいい。

    画像

    「全部」の意味を、自分の環境で確かめてみてほしい

    「全API対応」は嘘ではなかった。公開 OpenAPI の約2,900の操作が、同じ形のコマンドで叩ける。ただ、自分が Terraform に求めていたのは叩ける数ではなく、全体があるべき姿かを確かめられることだった。そこはまだ埋まっていない。

    cf を試した人に聞いてみたい。Terraform で書けずにダッシュボードで触っていた設定のうち、cf で届いたものはあっただろうか。逆に、公開 OpenAPI に無くて cf でも届かなかった機能があれば、その名前を知りたい。コメントで教えてもらえるとうれしいです。

    #Cloudflare #cf #Terraform #CLI #IaC #Wrangler #CloudflareWorkers #OpenAPI #インフラ #セキュリティ運用

     
     
    生成AIとローカルLLMの実機検証、自作プログラムの公開に加え、セキュリティと時事ネタの解説も書いています。セキュリティ関連ニュース、生成AI関連、モデル検証。ニュースの数字の裏側を、手元で確かめた結果と一緒に残します。

    あなたへのおすすめ