Guide des commandes cURL : options de base et avancées avec exemples

cURL permet d’envoyer des requêtes depuis votre terminal pour tester des API, examiner les réponses et transférer des données. Une requête simple tient sur une ligne. Mais ajoutez des paramètres de requête, un corps JSON, des en-têtes personnalisés et une apostrophe dans les données, et la construction de cette ligne peut devenir la partie la plus difficile du travail.

Notre générateur de commandes cURL gratuit propose des champs pour les détails de la requête et génère la commande au fil de la saisie. Il est particulièrement utile quand vous savez ce que vous voulez envoyer, mais préférez éviter de consacrer votre temps de débogage aux guillemets du shell.

Ce guide présente la disponibilité de cURL, des commandes pratiques, des options avancées et l’aide apportée par le générateur pour les requêtes API courantes.

Que peut-on faire avec cURL ?

La commande curl transfère des données à partir d’URL. Elle sert notamment à vérifier des en-têtes HTTP, appeler une API, envoyer des formulaires, télécharger des fichiers et rechercher des problèmes de connexion. Ses capacités dépassent HTTP et incluent des protocoles comme FTP, SMTP et SFTP, selon la version compilée installée. Consultez le manuel officiel de cURL (en anglais)  pour connaître les options et protocoles pris en charge.

Considérez une requête comme un ensemble de quatre éléments : l’URL, la méthode, les en-têtes et un corps facultatif. L’URL désigne la destination ; les autres éléments décrivent l’action et les données à envoyer. Le serveur décide comment les traiter.

cURL est-il disponible sous Windows, macOS et Linux ?

Oui. Commencez par ouvrir un terminal et vérifier votre installation :

curl --version

• Windows : cURL est fourni avec les installations actuelles de Windows 10 et Windows 11. Utilisez curl.exe --version dans PowerShell pour éviter qu’un éventuel alias curl appelle une autre commande. La version fournie peut avoir des capacités différentes de celles d’autres distributions. Consultez la page cURL sous Windows (en anglais) .
• macOS : le système d’exploitation inclut cURL. Sa version peut différer de celle d’une installation gérée par un autre gestionnaire de paquets. Consultez les notes d’installation pour macOS (en anglais) .
• Linux : installez le paquet cURL de votre distribution s’il manque. Le répertoire officiel des téléchargements (en anglais)  répertorie les paquets par plateforme et les autres versions compilées.

Les exemples ci-dessous utilisent des règles de guillemets compatibles avec Bash et Zsh, notamment dans WSL ou Git Bash. PowerShell et l’invite de commandes Windows ont des règles différentes pour les guillemets et la continuation des lignes ; disposer de cURL ne rend pas tous les exemples de shell interchangeables.

Les chemins d’API et noms de fichiers des exemples sont illustratifs. Remplacez-les par un point d’accès que vous contrôlez ou que vous êtes autorisé à utiliser ; les chemins d’exemple sur example.com ne sont pas des API de démonstration fonctionnelles.

Les options de base de cURL à connaître

Ces options sont décrites dans la référence des options cURL (en anglais) . Les noms longs sont plus lisibles ; les noms courts réduisent la saisie. Certaines options, dont --data-raw, n’ont pas de forme courte équivalente.

Envoyer une requête GET ou examiner les en-têtes

Pour une URL HTTP ordinaire, une requête simple utilise GET :

curl 'https://example.com/'

Pour demander les en-têtes sans le corps de réponse :

curl --head 'https://example.com/'

HEAD est une méthode de requête distincte ; un serveur peut donc la traiter différemment de GET. Utilisez le point d’accès approprié lorsque vous vérifiez le comportement d’une API.

Envoyer une requête POST avec un corps JSON

Voici le type de commande que vous pouvez produire avec le générateur :

curl \
  --request 'POST' \
  --url 'https://example.com/api/items' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{"name":"Demo item","quantity":2}'

Content-Type décrit le corps envoyé. Accept indique le format de réponse souhaité ; il n’oblige pas le serveur à le renvoyer. Le générateur conserve le corps tel quel et ne vérifie pas la validité du JSON.

Pour les commandes écrites à la main, cURL propose aussi le raccourci --json depuis la version 7.82.0. Il ajoute les en-têtes JSON et envoie les données, sans pour autant valider le JSON. Le générateur utilise actuellement des en-têtes explicites et --data-raw. Consultez le guide sur l’envoi de JSON avec cURL (en anglais) .

Pourquoi construire une URL et une commande cURL peut devenir compliqué

Il faut respecter plusieurs formats à la fois. Une URL suit la syntaxe des URL, le JSON suit la syntaxe JSON et le shell du terminal interprète la commande avant que cURL reçoive ses arguments.

Par exemple, les opérations suivantes sont distinctes :

1. Encodage d’URL : un espace dans la valeur d’un paramètre peut nécessiter %20 ; une esperluette qui fait partie de cette valeur doit être encodée pour ne pas servir de séparateur de paramètres.
2. Guillemets du shell : l’URL doit parvenir à cURL sous la forme d’un seul argument. Un & sans guillemets a un sens particulier dans Bash, même si vous vouliez l’inclure dans l’URL.
3. Guillemets du corps : les guillemets doubles du JSON doivent traverser le shell sans être supprimés, et une apostrophe dans une valeur complique l’utilisation de guillemets simples dans le shell.

Les guides du projet cURL expliquent l’encodage d’URL (en anglais)  et les guillemets autour des arguments d’options (en anglais) . Mettre une URL entre guillemets ne l’encode pas.

Cette URL déjà encodée reste lisible entre guillemets :

curl 'https://example.com/search?q=red%20shoes&sort=price'

Imaginez maintenant que vous vouliez envoyer ce corps JSON :

{"name":"O'Reilly","note":"Keep $5 as literal text"}

L’entourer de simples apostrophes de shell ne suffit plus, car le nom contient une apostrophe. Passer aux guillemets doubles sans précaution peut créer un autre problème : le shell risque d’interpréter les signes dollar. Le générateur applique l’échappement nécessaire pour le shell tout en préservant exactement votre saisie.

C’est là qu’un générateur de commandes peut vous faire gagner du temps : changez la méthode, collez le corps, ajoutez un en-tête et copiez la commande assemblée sans reconstruire les guillemets à la main. Vous pouvez ainsi examiner la réponse de l’API au lieu de compter les caractères de citation.

Le générateur laisse l’URL inchangée. Il ne la valide pas, n’encode pas les valeurs des paramètres et ne vérifie pas l’existence de la destination. Vous devez toujours fournir l’URL et les données adaptées à votre API.

Construire une commande cURL sans mémoriser la syntaxe

Ouvrez le générateur de commandes cURL en ligne et suivez ces étapes :

1. Sélectionnez GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS et saisissez votre URL.
2. Choisissez un Content-Type si nécessaire. Activez Accepter les réponses JSON lorsque cela convient.
3. Ajoutez des en-têtes personnalisés sous la forme Name: value, un par ligne. Chaque nom ne doit apparaître qu’une fois, y compris parmi les en-têtes prédéfinis.
4. Collez un corps pour une méthode qui le prend en charge dans le générateur. GET et HEAD omettent le corps tout en conservant votre brouillon si vous revenez à une autre méthode.
5. Activez Sortie détaillée pour rechercher un problème. Utilisez Accepter les certificats autosignés uniquement dans un environnement de test de confiance.
6. Sélectionnez éventuellement Options courtes ou Sortie sur une seule ligne. Ces deux options sont désactivées au départ. Copiez le résultat dans le terminal approprié.

La sortie multiligne par défaut vise les shells POSIX, dont Bash et Zsh. La sortie sur une seule ligne nécessite Bash ou Zsh et échappe les sauts de ligne du corps tout en préservant son contenu. Elle ne supprime pas silencieusement ces sauts de ligne.

L’outil accepte jusqu’à 10 en-têtes personnalisés, 8 192 caractères de texte pour ces en-têtes et 65 536 caractères pour le corps, mesurés en unités de chaîne JavaScript. Il est gratuit et ne nécessite pas de compte.

Les détails de la requête et la commande générée restent dans votre navigateur. Le générateur n’envoie pas la requête et n’enregistre pas votre saisie. L’exécution de la commande copiée dans votre terminal contacte la destination. Pour examiner l’activité du site lui-même, consultez notre guide pour vérifier les requêtes réseau d’un site avec les outils de développement du navigateur.

Options avancées de cURL pour des tâches plus complexes

Il s’agit de capacités de cURL lui-même. Le générateur actuel ne propose pas de commandes dédiées aux exemples avancés ci-dessous ; utilisez-les lorsque vous modifiez des commandes à la main.

Encoder automatiquement les paramètres de requête

Utilisez --get avec --data-urlencode pour construire une requête à partir de valeurs séparées :

curl --get \
  --url 'https://example.com/search' \
  --data-urlencode 'q=red shoes' \
  --data-urlencode 'category=books & magazines'

Ici, cURL encode les valeurs et les place dans les paramètres de l’URL. Cette opération diffère du collage d’une URL déjà assemblée dans le générateur. Consultez le guide sur la conversion de données de formulaire en requête GET (en anglais) .

Suivre les redirections et gérer les erreurs HTTP

--location suit les redirections. --fail-with-body fait produire un code de sortie d’échec aux réponses d’erreur HTTP tout en conservant leur corps, ce qui aide les scripts à détecter un téléchargement ou un appel API échoué :

curl --location --fail-with-body \
  --output 'report.json' \
  'https://example.com/api/report'

Choisissez un nouveau nom de fichier de sortie si vous devez conserver un fichier existant. Vérifiez soigneusement les redirections lorsque vous adaptez une commande POST : le code de redirection et les options de méthode influencent la requête suivante. Consultez les guides sur la gestion des redirections (en anglais)  et les réponses et erreurs HTTP (en anglais) .

Définir des délais et réessayer après un échec temporaire

curl --connect-timeout 5 --max-time 20 --retry 2 \
  'https://example.com/api/status'

Le délai de connexion limite l’établissement de la connexion ; la durée maximale limite chaque tentative de transfert. Les nouvelles tentatives peuvent prolonger la commande au-delà de 20 secondes. Toutes les erreurs ne déclenchent pas une nouvelle tentative, et répéter une requête qui modifie des données peut répéter une opération. Consultez les guides sur les délais (en anglais)  et les nouvelles tentatives (en anglais) .

Envoyer un fichier avec un formulaire multipart

curl --form 'description=Quarterly report' \
  --form 'file=@report.pdf' \
  'https://example.com/api/uploads'

Dans cet argument de formulaire, @report.pdf demande à cURL de lire un fichier local lors de l’exécution de la commande. Ce comportement diffère du corps littéral --data-raw du générateur. Laissez cURL construire le Content-Type multipart et sa limite de séparation. Consultez le guide sur les envois de formulaires multipart (en anglais) .

S’authentifier et configurer les certificats de confiance

Pour l’authentification HTTP Basic, curl --user 'demo' 'https://example.com/private' demande le mot de passe au lieu de le placer dans la commande. D’autres API utilisent des jetons dans les en-têtes ; suivez la documentation de l’API. Le générateur accepte déjà un en-tête Authorization personnalisé, mais ne gère pas les identifiants. Consultez le guide sur l’authentification HTTP (en anglais) .

Pour un certificat de développement, --cacert permet de préciser un fichier de certificat d’autorité de confiance. L’option Accepter les certificats autosignés du générateur ajoute à la place --insecure, qui désactive la vérification du certificat et du nom d’hôte. Elle n’installe pas de certificat et ne constitue pas une solution générale aux problèmes HTTPS. Consultez la documentation sur la vérification des certificats par cURL (en anglais) .

Questions fréquentes

Pourquoi ma commande cURL fonctionne-t-elle dans un terminal mais pas dans un autre ?

Vérifiez à la fois la version de cURL installée et le shell. Bash, Zsh, PowerShell et l’invite de commandes n’interprètent pas tous les guillemets et sauts de ligne de la même manière. Utilisez le format de shell indiqué par le générateur et examinez curl --version lorsqu’une option n’est pas disponible.

Le générateur envoie-t-il ma requête API ?

Non. Il génère le texte de la commande localement. Vous décidez quand et où l’exécuter. Une commande contenant des identifiants peut néanmoins être conservée dans l’historique du terminal ou exposée lors d’un partage, et la sortie détaillée peut contenir des en-têtes sensibles. Vérifiez les deux avant de les joindre à un ticket.

Puis-je utiliser le générateur pour des commandes cURL avancées ?

Utilisez-le pour assembler la méthode, l’URL, les en-têtes et le corps pris en charge, puis adaptez la commande copiée aux autres capacités de cURL. Les commandes dédiées à l’import, aux envois de fichiers, aux nouvelles tentatives et aux projets de requêtes enregistrés ne sont pas disponibles actuellement.

Prêt à mettre ces exemples en pratique ? Construisez votre commande cURL en regroupant la méthode, les en-têtes, le corps et les guillemets du shell au même endroit.