Qu'est-ce que la commande curl ? Exemples, options, requêtes HTTP

Qu'est-ce que la commande curl ?

curl est un outil en ligne de commande qui transfère des données vers ou depuis un serveur à partir d'une URL. On l'utilise surtout pour envoyer des requêtes HTTP depuis le terminal : appeler une API, examiner en-têtes et codes de statut ou envoyer un fichier. Une courte commande montre ce que le client a envoyé et ce que le serveur a répondu.

Il est né en 1996 sous la forme d'un petit outil appelé HttpGet, a été rebaptisé curl en 1998 et est maintenu par Daniel Stenberg. En plus de HTTP et HTTPS, il gère FTP, SFTP, SMTP, IMAP et de nombreux autres protocoles. La liste complète des options figure dans la page de manuel de curl.

Syntaxe de base de curl

La commande la plus simple envoie une requête GET et affiche le corps de la réponse :

curl https://api.example.com/users/42

Ajoutez -i pour voir aussi la ligne de statut et les en-têtes de réponse :

curl -i https://api.example.com/users/42

Quand vous donnez des données à curl avec -d, il envoie un POST par défaut : -X POST est donc facultatif. Les données partent en application/x-www-form-urlencoded, il faut donc définir vous-même l'en-tête pour du JSON :

curl -X POST https://api.example.com/users -H "Content-Type: application/json" -d '{"name": "Alice", "email": "alice@example.com"}'

Depuis curl 7.82.0, l'option --json le fait en une seule étape : elle envoie les données en POST avec les en-têtes JSON Content-Type et Accept, sans vérifier que le JSON est valide.

curl --json '{"name": "Alice"}' https://api.example.com/users

Les options curl les plus utilisées

Recettes curl courantes

Tester un point d'accès d'API

Appelez un point d'accès d'API (endpoint) et lisez la ligne de statut et les en-têtes :

curl -i https://api.example.com/health

Envoyer un jeton

Passez un jeton Bearer dans l'en-tête Authorization. Utilisez des guillemets doubles pour que le shell développe $TOKEN :

curl -H "Authorization: Bearer $TOKEN" https://api.example.com/orders/42

Envoyer un fichier

-F envoie une requête multipart/form-data :

curl -F "avatar=@photo.jpg" -F "username=alice" https://api.example.com/upload

Afficher uniquement le code de statut

curl -s -o /dev/null -w "%{http_code}\n" https://example.com

Mesurer le temps de réponse

Les variables de write-out donnent les temps d'une requête, y compris le temps jusqu'au premier octet :

curl -s -o /dev/null -w "ttfb %{time_starttransfer}s total %{time_total}s\n" https://example.com

Erreurs courantes avec curl

• Oublier le Content-Type JSON. Avec un simple -d, le corps part comme des données de formulaire et beaucoup d'API répondent 400 ou 415. Ajoutez l'en-tête ou utilisez --json. Notre article sur la façon dont les paramètres sont envoyés dans une requête HTTP POST (en anglais) explique les trois formats de corps.
• Ajouter -X POST à chaque -d. C'est redondant, et -X conserve la méthode même après une redirection, ce qui peut masquer le comportement réel.
• Les guillemets. Dans bash, les guillemets simples autour du JSON protègent les doubles à l'intérieur, mais empêchent aussi le développement de $TOKEN. L'invite de commandes Windows exige des guillemets doubles échappés.
• Des secrets dans l'historique. Un jeton saisi après -H se retrouve dans l'historique de votre shell. Lisez-le depuis une variable d'environnement ou un fichier.
• Se fier au code de sortie. Par défaut, curl considère qu'un 404 ou un 500 est un transfert réussi. Dans les scripts, ajoutez --fail, et utilisez --fail-with-body si vous voulez aussi le corps.
• Laisser -k dans un script. Il désactive la vérification du certificat : une attaque de l'homme du milieu passe inaperçue.
• Oublier -L. Sans lui, curl s'arrête au premier 301 ou 302.

curl pour les tests d'API, la CI et la surveillance

Comme curl est présent sur presque toutes les machines, c'est le moyen le plus rapide de reproduire un appel en échec et la brique habituelle des tests d'API dans un pipeline. Un test de fumée après un déploiement peut tenir en une ligne, avec un délai maximal et --fail pour qu'un mauvais statut fasse échouer le build :

curl --fail --max-time 10 -s -o /dev/null https://example.com/health

• Pas de terminal sous la main ? L'outil gratuit curl Online fonctionne comme curl dans le navigateur : envoyez des requêtes GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS et lisez le statut, les en-têtes, le corps, le certificat et le détail des temps. Les méthodes sûres partent de six régions AWS pour que vous puissiez comparer.
• Transformer une commande en test. Le convertisseur cURL vers k6 transforme une commande curl en script k6, et l'article sur l'import de cURL, HAR, Postman ou OpenAPI dans des tests de charge (en anglais) couvre les autres formats.
• Continuer à vérifier après le déploiement. Un curl dans cron s'écrit vite et s'oublie vite. La surveillance d'API lance la requête selon un calendrier depuis plusieurs emplacements, contrôle le statut, le corps, les en-têtes et le temps de réponse, et vous alerte. L'offre gratuite vérifie toutes les 5 minutes avec la surveillance d'API de LoadFocus.
• Pas un outil de test de charge. --parallel (depuis curl 7.66.0) exécute des transferts simultanément, jusqu'à 50 à la fois par défaut. Il rapporte chaque transfert, pas des centiles, une montée en charge ni des résultats par région, et il part d'une seule machine. Pour un trafic réel, utilisez des tests de charge depuis des régions cloud.

Questions fréquentes : commande curl

Quelle est la différence entre -d et --data-raw ?

Avec -d, une valeur qui commence par @ est lue comme un nom de fichier. Avec --data-raw, la même valeur est envoyée telle quelle. Utilisez --data-raw quand vos données commencent réellement par un caractère @.

Comment envoyer une méthode HTTP personnalisée ?

Avec -X, par exemple curl -X PUT ou curl -X DELETE. Vous n'avez normalement pas besoin de -X pour GET, HEAD ou POST, car curl choisit la méthode d'après les autres options.

Comment voir exactement ce que curl envoie ?

Ajoutez -v pour une sortie détaillée. Elle affiche les en-têtes de requête envoyés, les en-têtes de réponse reçus et des détails sur la connexion TLS.

Comment conserver les cookies entre plusieurs appels curl ?

Enregistrez-les avec -c cookies.txt (cookie jar) au premier appel et envoyez-les avec -b cookies.txt aux appels suivants.

curl peut-il exécuter des requêtes en parallèle ?

Oui. Depuis 7.66.0, l'option --parallel (-Z) exécute plusieurs transferts à la fois, 50 par défaut, et --parallel-max le modifie. C'est pratique pour des téléchargements, mais cela ne remplace pas un test de charge.

Puis-je utiliser curl comme outil de test de charge ?

Pour une poignée de requêtes simultanées, oui. Il n'agrège pas les résultats en centiles, ne monte pas en charge progressivement et ne part pas de plusieurs régions. Pour cela, convertissez l'appel en test k6 ou JMeter et exécutez-le dans le cloud.