Ein Praxisleitfaden für Cloudflares neue cf-CLI

cf ist Cloudflares Kommandozeilentool für die gesamte Cloudflare-API. Es ist am 28. September 2026 als Open Beta gestartet und wird mit npm i -g cf unter Node.js 22.18 oder neuer installiert.

Wenn Sie Workers mit Wrangler deployen, öffnen Sie vermutlich trotzdem noch das Dashboard für DNS, Zonen und Einstellungen, die Wrangler nie abgedeckt hat. cf deckt beides ab: Ihre Account-Ressourcen und Ihre Worker-Projekte, mit einem einzigen Binary. Dieser Leitfaden zeigt Ihnen, wie Sie das Tool installieren, seine Ausgabe auswerten, die neue TypeScript-Konfiguration schreiben, deployen und einen bestehenden Worker migrieren. Falls Sie zuerst Ihr Wissen zu Workers auffrischen möchten, beginnen Sie mit diesem Einsteigerleitfaden zu Cloudflare Workers.

Worin unterscheidet sich cf von Wrangler?

cf ersetzt eine CLI, die Befehl für Befehl gewachsen ist, durch eine, die aus Cloudflares OpenAPI-Schemas generiert wird. Laut Ankündigung zum Launch deckt cf mehr als 3.000 API-Operationen ab, gegenüber rund 280 in Wrangler. Die cf-Dokumentation zählt anders: mehr als 2.900 Befehle. Cloudflare hat cf mit Blick auf Coding Agents entwickelt, doch jeder Befehl funktioniert genauso, wenn Sie ihn selbst eintippen.

Der Changelog-Eintrag weist darauf hin, dass sich Befehle, Konfiguration und Build Output vor dem stabilen Release noch ändern können.

Wie installieren Sie cf und melden sich an?

Installieren Sie das Paket cf über npm und authentifizieren Sie sich anschließend mit cf auth login. Auch andere Tools installieren einen Befehl namens cf. Stellen Sie daher sicher, dass Sie das offizielle Paket verwenden, das auf das Repository cloudflare/cf verweist.

npm i -g cf
cf --version

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

Laut der Get-started-Dokumentation stellt das Paket dieselbe CLI unter zwei Namen bereit: cf und cloudflare. Falls ein anderes Programm in Ihrem PATH bereits auf cf reagiert, rufen Sie die CLI stattdessen als cloudflare auf. Für die Anmeldung zeigt cf einen Link und einen Einmalcode an und öffnet den Link anschließend in Ihrem Browser, wo Sie die Anmeldung bestätigen. cf speichert eigene Zugangsdaten, ein Wrangler-Login wird also nicht übernommen.

In CI-Umgebungen setzen Sie stattdessen CLOUDFLARE_API_TOKEN und CLOUDFLARE_ACCOUNT_ID. Ein auf diese Weise gesetztes Token hat Vorrang vor jedem gespeicherten Login.

Beginnen Sie mit einem rein lesenden Befehl:

cf zones list

Wie lesen und filtern Sie die JSON-Ausgabe von cf?

Die meisten cf-Befehle schreiben ihre Ergebnisse als JSON auf stdout, während Fortschritts- und Statusmeldungen an stderr gehen. Sie können Ergebnisse also ohne zusätzliche Flags in eine Datei speichern oder per Pipe an jq übergeben.

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

Wie die Dokumentation zur Ressourcenverwaltung zeigt, liefert cf zones list ein JSON-Array, in dem jede Zone ein Feld id besitzt. Befehle, die innerhalb einer Zone arbeiten, erwarten --zone oder die Kurzform -z und akzeptieren entweder eine Zonen-ID oder einen Domainnamen:

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

Befehle finden mit cf cli search

Um einen Befehl zu finden, führen Sie cf cli search mit einer Beschreibung der Aufgabe in natürlicher Sprache aus und öffnen dann die Hilfe zum vorgeschlagenen Befehl. Laut der Agents-Dokumentation liefert cf cli search bis zu fünf Treffer als JSON-Array, den besten Treffer zuerst. Die Suche läuft lokal auf Ihrem Rechner, Sie müssen also nicht angemeldet sein.

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

--help funktioniert auf jeder Ebene des Befehlsbaums.

Wie konfigurieren Sie Workers mit cloudflare.config.ts?

cloudflare.config.ts ist die TypeScript-Konfigurationsdatei von cf für Workers. Sie importiert defineConfig aus cf/config, exportiert das Ergebnis als Default Export und deklariert Bindings und Trigger über typisierte Helper, die Ihr Editor automatisch vervollständigen kann. Die Referenz zur programmatischen Konfiguration weist darauf hin, dass die Datei ein gewöhnliches TypeScript-Modul ist. Sie können darin also Imports, Funktionen, Umgebungsvariablen und asynchrone Werte verwenden.

Das erste Beispiel im Launch-Post importiert das Worker-Modul mit dem Import-Attribut with { type: "cf-worker" } und setzt anschließend name, entrypoint und compatibilityDate. In den folgenden Auszügen steht // ... für diese Felder. Dieser gekürzte Auszug aus dem bindings-Beispiel des Launch-Posts übergibt defineConfig eine Funktion, sodass Werte je nach mode variieren können:

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(),
    },
  },
}));

Das vollständige Beispiel verwendet außerdem bindings.text, bindings.kv, bindings.vectorize und bindings.worker. Trigger werden in einem einzigen Array definiert. Dieser Auszug übergibt defineConfig ein einfaches Objekt:

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 }),
    ],
  },
});

Die Version im Launch-Post ergänzt einen Eintrag triggers.email. Die Referenz führt zudem triggers.connect auf, das Raw Sockets abdeckt. Im Launch-Post kündigt Cloudflare an, dass diese Datei künftig auch Zonen und DNS einrichten können soll. Derzeit deckt der Default Export einen Worker, Container-Anwendungen und Account-Einstellungen ab.

Init, Deploy und Migrate

Verwenden Sie cf init für ein neues Projekt, cf deploy zum Ausliefern und cf migrate für ein bestehendes Wrangler-Projekt.

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

cf init erstellt cloudflare.config.ts und vite.config.ts und installiert in einer bestehenden Vite-App @cloudflare/vite-plugin. Ohne Argumente aufgerufen, hält der Befehl an und fragt nach einem Verzeichnis. Laut der Deploy-Dokumentation baut und prüft ein einziger Aufruf von cf deploy das Projekt, ermittelt die zu verwendenden Zugangsdaten und den Account, lädt anschließend eine neue Worker Version hoch und schaltet sie live. Eine statische Website benötigt vor ihrem ersten cf deploy keine Konfigurationsdatei.

Wenn Ihr Projekt eine wrangler.toml, wrangler.json oder wrangler.jsonc enthält, migrieren Sie es, bevor Sie cf dev, cf build oder cf deploy ausführen. Diese drei Befehle berücksichtigen ausschließlich cloudflare.config.ts und ignorieren jede Wrangler-Konfigurationsdatei.

cf migrate --dry-run
cf migrate

cf migrate liest TOML direkt ein, Sie müssen alte Dateien also nicht vorher konvertieren. Wenn Sie lediglich eine JSON-Ansicht einer älteren wrangler.toml benötigen, verwenden Sie einen TOML-zu-JSON-Konverter. Der Leitfaden „cf for Wrangler users“ erläutert, dass die Migration bei Wranglers Bundler bleibt, sofern das Projekt nicht bereits das Cloudflare-Vite-Plugin nutzt. Der Umstieg auf Vite ist also optional. Wenn Wranglers Bundler beibehalten wird, schreibt die Migration eine wrangler.config.ts, und laut der Migrationsdokumentation muss im Paket des Workers Wrangler 4.136.0 oder neuer installiert sein. Der Launch-Post ergänzt, dass auch Rust- und Python-Workers weiterhin an Wrangler delegieren.

Was passiert mit Wrangler?

Wrangler funktioniert vorerst weiter, sein Ende ist jedoch absehbar. Nach dem Ende der cf-Open-Beta plant Cloudflare, eine letzte Major-Version von Wrangler zu veröffentlichen, die Nutzer zu cf weiterleitet, und Wrangler ab diesem Zeitpunkt noch 18 Monate lang zu warten. Cloudflare hat noch nicht bekannt gegeben, wann die Beta endet, daher gibt es für die 18 Monate noch kein konkretes Datum.

Dass Vite zum Standard-Build wird, passt zu einer breiteren Hinwendung zu Vite im Workers-Ökosystem.

Fazit

Sie können cf parallel zu Wrangler installieren: Die Ressourcenbefehle laufen auch in einem nicht migrierten Projekt, und der Umstieg wird erst relevant, wenn Sie die Builds eines Workers auf cf umstellen. Installieren Sie das offizielle Paket, führen Sie cf zones list | jq . aus, um sich die Ausgabe selbst anzusehen, und testen Sie anschließend cf migrate --dry-run auf einem Branch eines unkritischen Workers, bevor die Beta endet und Wranglers Wartungszeitraum beginnt.

FAQs

Wie verwende ich cf mit mehr als einem Cloudflare-Account?

Verwenden Sie benannte Profile. Führen Sie cf auth create work aus, um ein Profil anzulegen und sich damit anzumelden, und anschließend cf auth activate work, um es mit dem aktuellen Ordner und allen darunterliegenden Ordnern zu verknüpfen. Übergeben Sie --profile work, um ein Profil für einen einzelnen Befehl zu verwenden, und nutzen Sie cf auth list, um alle Profile anzuzeigen. Eine Umgebungsvariable CLOUDFLARE_API_TOKEN überschreibt jedes Profil und blockiert Befehle zur Profilverwaltung, solange sie gesetzt ist.

Kann cf Zugangsdaten aus einer .env-Datei lesen?

Ja. API-Befehle können CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID und CLOUDFLARE_ZONE_ID aus einer .env-Datei in dem Ordner übernehmen, in dem Sie sie ausführen. cf berücksichtigt nur .env, nicht .env.local. Stellen Sie daher sicher, dass .env in der .gitignore aufgeführt ist. Ein auf diese Weise geladenes Token hat Vorrang vor jedem Profil und jedem gespeicherten Login. cf unterstützt den Global API Key nicht, verwenden Sie stattdessen ein API-Token mit eingeschränkten Berechtigungen.

Wie migriere ich ein Wrangler-Projekt innerhalb eines Monorepos?

Übergeben Sie cf migrate den Pfad zur Konfigurationsdatei, zum Beispiel cf migrate packages/api/wrangler.jsonc --dry-run, und führen Sie denselben Befehl anschließend ohne --dry-run aus. Ohne Pfadangabe erwartet cf migrate genau eine wrangler.json, wrangler.jsonc oder wrangler.toml im aktuellen Verzeichnis. Der Befehl schreibt seine Dateien neben die Konfigurationsdatei, wählt den Bundler anhand der package.json, sofern Sie nicht --bundler vite oder --bundler wrangler übergeben, und benötigt --force, wenn der Git-Worktree nicht sauber ist.

Was passiert, wenn ich cf deploy in einem Wrangler-Projekt vor der Migration ausführe?

cf ignoriert wrangler.jsonc und wrangler.toml und kann das Projekt daher eigenständig neu einrichten und dabei Dateien wie package.json ändern. Um das rückgängig zu machen, führen Sie git status aus, stellen jede geänderte Datei mit git restore wieder her und löschen neu angelegte Dateien wie cloudflare.config.ts, wrangler.config.ts sowie das Verzeichnis .cloudflare. Führen Sie anschließend cf migrate aus. Der Befehl läuft nicht, solange eine cloudflare.config.ts vorhanden ist.