Wrangler CLI

Vos connaissances des flags Wrangler CLI, des champs de configuration et des sous-commandes peuvent être obsolètes. Privilégiez la récupération à la pré-formation pour toute tâche Wrangler.

Sources de récupération

Récupérez les informations les plus récentes avant d'écrire ou d'examiner des commandes et une configuration Wrangler. Ne vous fiez pas aux connaissances intégrées pour les flags CLI, les champs de configuration ou les formes de liaison.

PREMIER : Vérifiez que Wrangler est installé, et sinon, installez-le

Vérifiez que Wrangler est installé en exécutant :

wrangler --version  # Requires v4.x+

Si Wrangler n'est pas installé, vous devez l'installer en exécutant :

npm install -D wrangler@latest

Autant que possible, vous devez utiliser Wrangler plutôt que de construire manuellement des requêtes API.

Directives clés

• Utilisez wrangler.jsonc : Préférez la configuration JSON à TOML. Les fonctionnalités les plus récentes sont JSON uniquement.
• Définissez compatibility_date : Utilisez une date récente (dans les 30 jours). Consultez https://developers.cloudflare.com/workers/configuration/compatibility-dates/
• Générez les types après les changements de configuration : Exécutez wrangler types pour mettre à jour les liaisons TypeScript.
• Le développement local utilise par défaut le stockage local : Les liaisons utilisent la simulation locale sauf si remote: true.
• Profilez le démarrage du Worker : Exécutez wrangler check startup pour mesurer le temps de démarrage et détecter les scripts qui dépassent la limite.
• Utilisez les environnements pour la staging/prod : Définissez env.staging et env.production dans la configuration.

Démarrage rapide : Nouveau Worker

# Initialiser un nouveau projet
npx wrangler init my-worker

# Ou avec un framework
npx create-cloudflare@latest my-app

Référence rapide : Commandes principales

Configuration (wrangler.jsonc)

Configuration minimale

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01"
}

Configuration complète avec liaisons

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "compatibility_flags": ["nodejs_compat"],

  // Variables d'environnement
  "vars": {
    "ENVIRONMENT": "production"
  },

  // Espace de noms KV
  "kv_namespaces": [
    { "binding": "KV", "id": "<KV_NAMESPACE_ID>" }
  ],

  // Bucket R2
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket" }
  ],

  // Base de données D1
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" }
  ],

  // Workers AI (toujours distant)
  "ai": { "binding": "AI" },

  // Vectorize
  "vectorize": [
    { "binding": "VECTOR_INDEX", "index_name": "my-index" }
  ],

  // Hyperdrive
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }
  ],

  // Durable Objects
  "durable_objects": {
    "bindings": [
      { "name": "COUNTER", "class_name": "Counter" }
    ]
  },

  // Déclencheurs cron
  "triggers": {
    "crons": ["0 * * * *"]
  },

  // Environnements
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "vars": { "ENVIRONMENT": "staging" }
    }
  }
}

Générer les types à partir de la configuration

# Générer worker-configuration.d.ts
wrangler types

# Chemin de sortie personnalisé
wrangler types ./src/env.d.ts

# Vérifier que les types sont à jour (CI)
wrangler types --check

Développement local

Démarrer le serveur de développement

# Mode local (par défaut) - utilise la simulation du stockage local
wrangler dev

# Avec un environnement spécifique
wrangler dev --env staging

# Forcer local uniquement (désactiver les liaisons distantes)
wrangler dev --local

# Mode distant - s'exécute sur l'edge Cloudflare (hérité)
wrangler dev --remote

# Port personnalisé
wrangler dev --port 8787

# Rechargement en direct pour les changements HTML
wrangler dev --live-reload

# Tester les gestionnaires planifiés/cron
wrangler dev --test-scheduled
# Puis visitez : http://localhost:8787/__scheduled

Liaisons distantes pour le développement local

Utilisez remote: true dans la configuration de liaison pour vous connecter à des ressources réelles lors de l'exécution locale :

{
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true }
  ],
  "ai": { "binding": "AI", "remote": true },
  "vectorize": [
    { "binding": "INDEX", "index_name": "my-index", "remote": true }
  ]
}

Liaisons distantes recommandées : AI (obligatoire), Vectorize, Browser Rendering, mTLS, Images.

Secrets locaux

Créez .dev.vars pour les secrets de développement local :

API_KEY=local-dev-key
DATABASE_URL=postgres://localhost:5432/dev

Déploiement

Déployer le Worker

# Déployer en production
wrangler deploy

# Déployer un environnement spécifique
wrangler deploy --env staging

# Test d'exécution (valider sans déployer)
wrangler deploy --dry-run

# Garder les variables définies dans le tableau de bord
wrangler deploy --keep-vars

# Minifier le code
wrangler deploy --minify

Gérer les secrets

Sécurité : Ne passez jamais de valeurs secrètes comme arguments de commande ou via echo. Utilisez l'invite interactive (préféré), le tuyau depuis un fichier ou secret bulk. Ne sortez jamais, ne journalisez pas et ne codez pas en dur les valeurs secrètes dans les commandes.

# Définir le secret — invite interactive (préféré, wrangler demandera la valeur en toute sécurité)
wrangler secret put API_KEY

# Définir le secret à partir d'un fichier (utile pour les clés PEM, environnements CI)
wrangler secret put PRIVATE_KEY < path/to/private-key.pem

# Lister les secrets
wrangler secret list

# Supprimer le secret
wrangler secret delete API_KEY

# Secrets en masse à partir d'un fichier JSON (ne committez pas ce fichier au contrôle de version)
wrangler secret bulk secrets.json

Versions et restauration

# Lister les versions récentes
wrangler versions list

# Voir la version spécifique
wrangler versions view <VERSION_ID>

# Restaurer à la version précédente
wrangler rollback

# Restaurer à une version spécifique
wrangler rollback <VERSION_ID>

KV (Magasin de clé-valeur)

Gérer les espaces de noms

# Créer un espace de noms
wrangler kv namespace create MY_KV

# Lister les espaces de noms
wrangler kv namespace list

# Supprimer l'espace de noms
wrangler kv namespace delete --namespace-id <ID>

Gérer les clés

# Ajouter une valeur
wrangler kv key put --namespace-id <ID> "key" "value"

# Ajouter avec expiration (secondes)
wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600

# Obtenir la valeur
wrangler kv key get --namespace-id <ID> "key"

# Lister les clés
wrangler kv key list --namespace-id <ID>

# Supprimer la clé
wrangler kv key delete --namespace-id <ID> "key"

# Ajout en masse depuis JSON
wrangler kv bulk put --namespace-id <ID> data.json

Liaison de configuration

{
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<NAMESPACE_ID>" }
  ]
}

R2 (Stockage d'objets)

Gérer les buckets

# Créer un bucket
wrangler r2 bucket create my-bucket

# Créer avec indication de localisation
wrangler r2 bucket create my-bucket --location wnam

# Lister les buckets
wrangler r2 bucket list

# Obtenir les informations du bucket
wrangler r2 bucket info my-bucket

# Supprimer le bucket
wrangler r2 bucket delete my-bucket

Gérer les objets

# Télécharger l'objet
wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt

# Télécharger l'objet
wrangler r2 object get my-bucket/path/file.txt

# Supprimer l'objet
wrangler r2 object delete my-bucket/path/file.txt

Liaison de configuration

{
  "r2_buckets": [
    { "binding": "ASSETS", "bucket_name": "my-bucket" }
  ]
}

D1 (Base de données SQL)

Gérer les bases de données

# Créer une base de données
wrangler d1 create my-database

# Créer avec localisation
wrangler d1 create my-database --location wnam

# Lister les bases de données
wrangler d1 list

# Obtenir les informations de la base de données
wrangler d1 info my-database

# Supprimer la base de données
wrangler d1 delete my-database

Exécuter SQL

# Exécuter une commande SQL (distant)
wrangler d1 execute my-database --remote --command "SELECT * FROM users"

# Exécuter un fichier SQL (distant)
wrangler d1 execute my-database --remote --file ./schema.sql

# Exécuter localement
wrangler d1 execute my-database --local --command "SELECT * FROM users"

Migrations

# Créer la migration
wrangler d1 migrations create my-database create_users_table

# Lister les migrations en attente
wrangler d1 migrations list my-database --local

# Appliquer les migrations localement
wrangler d1 migrations apply my-database --local

# Appliquer les migrations à distance
wrangler d1 migrations apply my-database --remote

Exporter/Sauvegarder

# Exporter le schéma et les données
wrangler d1 export my-database --remote --output backup.sql

# Exporter le schéma uniquement
wrangler d1 export my-database --remote --output schema.sql --no-data

Liaison de configuration

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "<DATABASE_ID>",
      "migrations_dir": "./migrations"
    }
  ]
}

Vectorize (Base de données vectorielle)

Gérer les index

# Créer un index avec dimensions
wrangler vectorize create my-index --dimensions 768 --metric cosine

# Créer avec préréglage (configure automatiquement les dimensions/métrique)
wrangler vectorize create my-index --preset @cf/baai/bge-base-en-v1.5

# Lister les index
wrangler vectorize list

# Obtenir les informations sur l'index
wrangler vectorize get my-index

# Supprimer l'index
wrangler vectorize delete my-index

Gérer les vecteurs

# Insérer des vecteurs à partir du fichier NDJSON
wrangler vectorize insert my-index --file vectors.ndjson

# Vecteurs de requête
wrangler vectorize query my-index --vector "[0.1, 0.2, ...]" --top-k 10

Liaison de configuration

{
  "vectorize": [
    { "binding": "SEARCH_INDEX", "index_name": "my-index" }
  ]
}

Hyperdrive (Accélérateur de base de données)

Gérer les configurations

# Créer une configuration
wrangler hyperdrive create my-hyperdrive \
  --origin-host db.example.com \
  --origin-port 5432 \
  --database my-database \
  --origin-user db-user \
  --origin-password "$DB_PASSWORD"

# Ou en utilisant une chaîne de connexion à partir d'une variable d'environnement
wrangler hyperdrive create my-hyperdrive \
  --connection-string "$HYPERDRIVE_CONNECTION_STRING"

# Lister les configurations
wrangler hyperdrive list

# Obtenir les détails de la configuration
wrangler hyperdrive get <HYPERDRIVE_ID>

# Mettre à jour la configuration
wrangler hyperdrive update <HYPERDRIVE_ID> \
  --origin-password "$DB_PASSWORD"

# Supprimer la configuration
wrangler hyperdrive delete <HYPERDRIVE_ID>

Liaison de configuration

{
  "compatibility_flags": ["nodejs_compat"],
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }
  ]
}

Workers AI

Lister les modèles

# Lister les modèles disponibles
wrangler ai models

# Lister les fine-tunes
wrangler ai finetune list

Liaison de configuration

{
  "ai": { "binding": "AI" }
}

Remarque : Workers AI s'exécute toujours à distance et entraîne des frais d'utilisation même en développement local.

Files

Gérer les files

# Créer la file
wrangler queues create my-queue

# Lister les files
wrangler queues list

# Supprimer la file
wrangler queues delete my-queue

# Ajouter un consommateur à la file
wrangler queues consumer add my-queue my-worker

# Retirer le consommateur
wrangler queues consumer remove my-queue my-worker

Liaison de configuration

{
  "queues": {
    "producers": [
      { "binding": "MY_QUEUE", "queue": "my-queue" }
    ],
    "consumers": [
      {
        "queue": "my-queue",
        "max_batch_size": 10,
        "max_batch_timeout": 30
      }
    ]
  }
}

Conteneurs

Construire et envoyer des images

# Construire l'image du conteneur
wrangler containers build -t my-app:latest .

# Construire et envoyer en une commande
wrangler containers build -t my-app:latest . --push

# Envoyer l'image existante au registre Cloudflare
wrangler containers push my-app:latest

Gérer les conteneurs

# Lister les conteneurs
wrangler containers list

# Obtenir les informations du conteneur
wrangler containers info <CONTAINER_ID>

# Supprimer le conteneur
wrangler containers delete <CONTAINER_ID>

Gérer les images

# Lister les images du registre
wrangler containers images list

# Supprimer l'image
wrangler containers images delete my-app:latest

Gérer les registres externes

Sécurité : Ne codez jamais en dur les identifiants de registre dans les commandes. Utilisez des variables d'environnement.

# Lister les registres configurés
wrangler containers registries list

# Configurer le registre externe (par exemple, ECR)
wrangler containers registries configure <DOMAIN> \
  --aws-access-key-id "$AWS_ACCESS_KEY_ID"

# Configurer DockerHub
wrangler containers registries configure <DOMAIN> \
  --dockerhub-username "$DOCKERHUB_USERNAME"

# Supprimer la configuration de registre
wrangler containers registries delete <DOMAIN>

Workflows

Gérer les workflows

# Lister les workflows
wrangler workflows list

# Décrire le workflow
wrangler workflows describe my-workflow

# Déclencher l'instance du workflow
wrangler workflows trigger my-workflow

# Déclencher avec des paramètres
wrangler workflows trigger my-workflow --params '{"key": "value"}'

# Supprimer le workflow
wrangler workflows delete my-workflow

Gérer les instances de workflow

# Lister les instances
wrangler workflows instances list my-workflow

# Décrire l'instance
wrangler workflows instances describe my-workflow <INSTANCE_ID>

# Terminer l'instance
wrangler workflows instances terminate my-workflow <INSTANCE_ID>

Liaison de configuration

{
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow"
    }
  ]
}

Pipelines

Gérer les pipelines

# Créer le pipeline
wrangler pipelines create my-pipeline --r2 my-bucket

# Lister les pipelines
wrangler pipelines list

# Afficher les détails du pipeline
wrangler pipelines show my-pipeline

# Mettre à jour le pipeline
wrangler pipelines update my-pipeline --batch-max-mb 100

# Supprimer le pipeline
wrangler pipelines delete my-pipeline

Liaison de configuration

{
  "pipelines": [
    { "binding": "MY_PIPELINE", "pipeline": "my-pipeline" }
  ]
}

Magasin de secrets

Gérer les magasins

# Créer le magasin
wrangler secrets-store store create my-store

# Lister les magasins
wrangler secrets-store store list

# Supprimer le magasin
wrangler secrets-store store delete <STORE_ID>

Gérer les secrets du magasin

# Ajouter le secret au magasin
wrangler secrets-store secret put <STORE_ID> my-secret

# Lister les secrets du magasin
wrangler secrets-store secret list <STORE_ID>

# Obtenir le secret
wrangler secrets-store secret get <STORE_ID> my-secret

# Supprimer le secret du magasin
wrangler secrets-store secret delete <STORE_ID> my-secret

Liaison de configuration

{
  "secrets_store_secrets": [
    {
      "binding": "MY_SECRET",
      "store_id": "<STORE_ID>",
      "secret_name": "my-secret"
    }
  ]
}

Pages (Déploiement frontend)

# Créer le projet Pages
wrangler pages project create my-site

# Déployer le répertoire sur Pages
wrangler pages deploy ./dist

# Déployer avec une branche spécifique
wrangler pages deploy ./dist --branch main

# Lister les déploiements
wrangler pages deployment list --project-name my-site

Observabilité

Tails des logs

# Diffuser les logs en direct
wrangler tail

# Tail du Worker spécifique
wrangler tail my-worker

# Filtrer par statut
wrangler tail --status error

# Filtrer par terme de recherche
wrangler tail --search "error"

# Sortie JSON
wrangler tail --format json

Configuration de la journalisation

{
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  }
}

Tests

Tests locaux avec Vitest

npm install -D @cloudflare/vitest-pool-workers vitest

vitest.config.ts:

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: {
        wrangler: { configPath: "./wrangler.jsonc" },
      },
    },
  },
});

Tester les événements planifiés

# Activer en développement
wrangler dev --test-scheduled

# Déclencher via HTTP
curl http://localhost:8787/__scheduled

Dépannage

Problèmes courants

Commandes de débogage

# Vérifier le statut d'authentification
wrangler whoami

# Profiler le temps de démarrage du Worker
wrangler check startup

# Afficher le schéma de configuration
wrangler docs configuration

Bonnes pratiques

1. Versionnez wrangler.jsonc : Traitez comme source de vérité pour la configuration du Worker.
2. Utilisez l'approvisionnement automatique : Omettez les ID de ressource pour la création automatique au déploiement.
3. Exécutez wrangler types en CI : Ajoutez à l'étape de construction pour détecter les décalages de liaison.
4. Utilisez les environnements : Séparez la staging/production avec env.staging, env.production.
5. Définissez compatibility_date : Mettez à jour trimestriellement pour obtenir les nouvelles fonctionnalités du runtime.
6. Utilisez .dev.vars pour les secrets locaux : Ne committez jamais les secrets à la configuration.
7. Testez localement d'abord : wrangler dev avec les liaisons locales avant de déployer.
8. Utilisez --dry-run avant les déploiements majeurs : Validez les changements sans déploiement.
9. Ne mettez jamais les secrets dans les commandes : Utilisez les invites interactives (wrangler secret put), l'entrée basée sur fichier (wrangler secret bulk), ou les variables d'environnement CI sécurisées. Ne faites jamais d'écho, de journalisation ou de passage de valeurs secrètes comme arguments CLI.