Guide pratique de la nouvelle CLI cf de Cloudflare

cf est l’outil en ligne de commande de Cloudflare qui couvre l’intégralité de l’API Cloudflare. Il est disponible en bêta ouverte depuis le 28 septembre 2026 et s’installe avec npm i -g cf sur Node.js 22.18 ou version ultérieure.

Si vous déployez des Workers avec Wrangler, vous ouvrez sans doute encore le tableau de bord pour gérer le DNS, les zones et les paramètres que Wrangler n’a jamais pris en charge. cf couvre les deux : les ressources de votre compte et vos projets Worker, depuis un seul binaire. Ce guide vous accompagne pas à pas : installation, lecture de la sortie, rédaction de la nouvelle configuration TypeScript, déploiement et migration d’un Worker existant. Si vous avez besoin d’une remise à niveau sur les Workers, commencez par ce guide pour débutants sur Cloudflare Workers.

En quoi cf diffère-t-il de Wrangler ?

cf remplace une CLI qui s’est enrichie commande après commande par une CLI générée à partir des schémas OpenAPI de Cloudflare. L’annonce de lancement attribue à cf plus de 3 000 opérations d’API, contre environ 280 pour Wrangler. La documentation de cf les compte différemment : plus de 2 900 commandes. Cloudflare a conçu cf en pensant aux agents de codage, mais chaque commande fonctionne exactement de la même façon lorsque vous la saisissez vous-même.

L’entrée du changelog précise que les commandes, la configuration et le Build Output sont encore susceptibles d’évoluer avant la version stable.

Comment installer cf et se connecter ?

Installez le paquet cf depuis npm, puis authentifiez-vous avec cf auth login. D’autres outils installent aussi une commande nommée cf : assurez-vous donc d’utiliser le paquet officiel, qui renvoie vers le dépôt cloudflare/cf.

npm i -g cf
cf --version

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

D’après la documentation de prise en main, le paquet fournit la même CLI sous deux noms, cf et cloudflare. Si une autre commande de votre PATH répond déjà au nom cf, utilisez plutôt cloudflare. Pour la connexion, cf affiche un lien et un code à usage unique, puis ouvre ce lien dans votre navigateur afin que vous puissiez valider l’accès. cf stocke ses propres identifiants : une connexion Wrangler ne sera donc pas reprise.

En CI, définissez plutôt CLOUDFLARE_API_TOKEN et CLOUDFLARE_ACCOUNT_ID. Un token défini de cette manière prend le pas sur toute connexion enregistrée.

Commencez par une commande en lecture seule :

cf zones list

Comment lire et filtrer la sortie JSON de cf ?

La plupart des commandes cf écrivent leurs résultats en JSON sur stdout, tandis que les messages de progression et d’état sont envoyés sur stderr. Vous pouvez ainsi enregistrer les résultats dans un fichier ou les rediriger vers jq sans option supplémentaire.

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

Comme le montre la documentation sur la gestion des ressources, cf zones list renvoie un tableau JSON dans lequel chaque zone possède un champ id. Les commandes qui agissent au sein d’une zone acceptent --zone ou sa forme courte -z, avec comme valeur un ID de zone ou un nom de domaine :

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

Trouver des commandes avec cf cli search

Pour trouver une commande, exécutez cf cli search en décrivant la tâche en langage courant, puis affichez l’aide de la commande suggérée. Selon la documentation consacrée aux agents, cf cli search renvoie jusqu’à cinq résultats sous forme de tableau JSON, classés par pertinence. La recherche s’effectue en local sur votre machine : vous n’avez donc pas besoin d’être connecté.

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

--help fonctionne à tous les niveaux de l’arborescence des commandes.

Comment configurer des Workers avec cloudflare.config.ts ?

cloudflare.config.ts est le fichier de configuration TypeScript de cf pour les Workers. Il importe defineConfig depuis cf/config, exporte le résultat par défaut et déclare les bindings et les triggers à l’aide de helpers typés que votre éditeur peut autocompléter. La référence sur la configuration programmatique souligne qu’il s’agit d’un module TypeScript classique : vous pouvez donc y utiliser des imports, des fonctions, des variables d’environnement et des valeurs asynchrones.

Le premier exemple de l’annonce de lancement importe le module du Worker avec l’attribut d’import with { type: "cf-worker" }, puis définit name, entrypoint et compatibilityDate. Dans les extraits ci-dessous, // ... remplace ces champs. Cet extrait simplifié de l’exemple bindings de l’annonce passe une fonction à defineConfig afin que les valeurs puissent varier selon le mode :

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

L’exemple complet utilise également bindings.text, bindings.kv, bindings.vectorize et bindings.worker. Les triggers sont regroupés dans un seul tableau. Cet extrait passe un simple objet à 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 }),
    ],
  },
});

La version de l’annonce ajoute une entrée triggers.email. La référence mentionne aussi triggers.connect, destiné aux sockets bruts. Dans l’annonce de lancement, Cloudflare indique prévoir que ce fichier puisse également configurer les zones et le DNS. Pour l’instant, l’export par défaut couvre un Worker, des applications Container et les paramètres du compte.

Initialiser, déployer et migrer

Utilisez cf init pour un nouveau projet, cf deploy pour le déployer et cf migrate pour un projet Wrangler existant.

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

cf init crée cloudflare.config.ts et vite.config.ts et, dans une application Vite existante, installe @cloudflare/vite-plugin. Lancée sans argument, la commande s’interrompt et demande un répertoire. D’après la documentation sur le déploiement, un seul appel à cf deploy compile et vérifie le projet, détermine les identifiants et le compte à utiliser, puis téléverse une nouvelle Worker Version et la met en production. Un site statique ne nécessite aucun fichier de configuration avant son premier cf deploy.

Si votre projet contient un fichier wrangler.toml, wrangler.json ou wrangler.jsonc, migrez-le avant d’exécuter cf dev, cf build ou cf deploy. Ces trois commandes ne lisent que cloudflare.config.ts et ignorent tout fichier de configuration Wrangler.

cf migrate --dry-run
cf migrate

cf migrate lit directement le TOML : inutile de convertir vos anciens fichiers au préalable. Si vous souhaitez simplement obtenir une vue JSON d’un ancien wrangler.toml, utilisez un convertisseur TOML vers JSON. Le guide cf destiné aux utilisateurs de Wrangler explique que la migration conserve le bundler de Wrangler, sauf si le projet utilise déjà le plugin Vite de Cloudflare : le passage à Vite reste donc facultatif. Lorsque le bundler de Wrangler est conservé, la migration génère un fichier wrangler.config.ts, et la documentation de migration précise que Wrangler 4.136.0 ou une version ultérieure doit être installé dans le paquet du Worker. L’annonce de lancement ajoute que les Workers Rust et Python continuent eux aussi de déléguer à Wrangler.

Quel avenir pour Wrangler ?

Wrangler continue de fonctionner pour le moment, mais sa fin de vie est actée. À l’issue de la bêta ouverte de cf, Cloudflare prévoit de publier une dernière version majeure de Wrangler qui orientera les utilisateurs vers cf, puis d’assurer la maintenance de Wrangler pendant 18 mois à compter de cette date. Cloudflare n’ayant pas encore annoncé la fin de la bêta, ces 18 mois ne correspondent pour l’instant à aucune date précise.

L’adoption de Vite comme outil de build par défaut s’inscrit dans un mouvement plus large vers Vite au sein de l’écosystème Workers.

Conclusion

Vous pouvez installer cf en parallèle de Wrangler : ses commandes de gestion des ressources fonctionnent dans un projet non migré, et la bascule ne devient significative que lorsque vous lui confiez les builds d’un Worker. Installez le paquet officiel, exécutez cf zones list | jq . pour découvrir la sortie par vous-même, puis testez cf migrate --dry-run sur une branche d’un Worker non critique avant la fin de la bêta et le début de la période de maintenance de Wrangler.

FAQ

Comment utiliser cf avec plusieurs comptes Cloudflare ?

Utilisez des profils nommés. Exécutez cf auth create work pour créer un profil et vous y connecter, puis cf auth activate work pour l'associer au dossier courant et à tous ses sous-dossiers. Passez --profile work pour utiliser un profil le temps d'une seule commande, et cf auth list pour afficher tous les profils. Une variable d'environnement CLOUDFLARE_API_TOKEN prend le pas sur tous les profils et bloque les commandes de gestion des profils tant qu'elle est définie.

cf peut-il lire des identifiants depuis un fichier .env ?

Oui. Les commandes d'API peuvent récupérer CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID et CLOUDFLARE_ZONE_ID depuis un fichier .env situé dans le dossier à partir duquel vous les exécutez. cf ne lit que .env, et non .env.local : vérifiez donc que .env figure bien dans votre .gitignore. Un token chargé de cette manière est prioritaire sur tout profil ou toute connexion enregistrée. cf ne prend pas en charge la Global API Key : utilisez plutôt un API token à portée limitée.

Comment migrer un projet Wrangler au sein d'un monorepo ?

Passez le chemin du fichier de configuration à cf migrate, par exemple cf migrate packages/api/wrangler.jsonc --dry-run, puis exécutez la même commande sans --dry-run. Sans chemin, cf migrate s'attend à trouver exactement un fichier wrangler.json, wrangler.jsonc ou wrangler.toml dans le répertoire courant. La commande écrit ses fichiers à côté du fichier de configuration, choisit le bundler en fonction du package.json sauf si vous passez --bundler vite ou --bundler wrangler, et nécessite --force si le worktree Git contient des modifications non commitées.

Que se passe-t-il si j'exécute cf deploy dans un projet Wrangler avant de le migrer ?

cf ignore wrangler.jsonc et wrangler.toml : il peut donc configurer le projet de son côté et modifier des fichiers comme package.json. Pour revenir en arrière, exécutez git status, restaurez chaque fichier modifié avec git restore et supprimez les nouveaux fichiers, comme cloudflare.config.ts, wrangler.config.ts et le répertoire .cloudflare. Exécutez ensuite cf migrate, qui refuse de s'exécuter tant qu'un fichier cloudflare.config.ts est présent.