La commande curl transfère des données entre votre terminal et un serveur. Elle permet de récupérer une page, télécharger un fichier, envoyer du JSON ou examiner une réponse HTTP. Pour commencer, exécutez curl https://example.com : le contenu reçu s’affiche directement dans le terminal, sans interprétation graphique comme dans un navigateur.
Prendre ses repères avant la première requête
La syntaxe générale est curl [options] [URL]. En HTTP, curl utilise GET par défaut. Les options modifient ensuite la requête, sa destination ou le traitement de la réponse. Placez les URL entre guillemets lorsqu’elles contiennent des caractères que le shell pourrait interpréter, notamment le signe &.
Vérifier l’installation selon votre système
Exécutez curl --version pour connaître la version, les protocoles et les fonctionnalités disponibles. Sous Debian ou Ubuntu, l’installation passe par sudo apt update && sudo apt install curl ; sous Fedora, utilisez sudo dnf install curl. Sur macOS, curl est généralement déjà présent ; Homebrew permet aussi de l’installer avec brew install curl.
Windows intègre curl.exe depuis Windows 10 version 1803, ainsi que dans Windows Server 2019. Dans Windows PowerShell 5.1, curl peut désigner un alias d’Invoke-WebRequest : préférez curl.exe --version pour lever l’ambiguïté. Les exemples ci-dessous utilisent la syntaxe d’un shell Linux ou macOS ; les guillemets et variables peuvent nécessiter une adaptation sous Windows.
Choisir curl plutôt qu’un autre outil
curl convient aux transferts précis et automatisables, notamment aux appels d’API. wget est particulièrement pratique pour les téléchargements récursifs. Postman propose une interface graphique pour organiser des collections de requêtes et travailler en équipe. curl, lui, conserve l’avantage d’une commande facile à intégrer dans un script ou un pipeline CI/CD.
Télécharger et envoyer des fichiers sans confondre les options
Sans option d’enregistrement, curl écrit la réponse sur la sortie standard. Pour un fichier binaire, indiquez donc une destination. Les commandes suivantes illustrent les usages courants ; remplacez les URL et chemins d’exemple par vos ressources réelles.
| Objectif | Commande | Point d’attention |
|---|---|---|
| Choisir le nom local | curl -L -o archive.zip "https://example.com/archive.zip" | -o définit explicitement le fichier de destination. |
| Conserver le nom de l’URL | curl -L -O "https://example.com/archive.zip" | -O utilise le dernier segment de l’URL. |
| Reprendre un transfert | curl -L -C - -o archive.zip "https://example.com/archive.zip" | Le serveur doit accepter la reprise. |
| Limiter le débit | curl --limit-rate 2M -O "https://example.com/archive.zip" | La limite s’applique au transfert. |
-L suit les redirections, notamment les réponses 301 et 302. Les fichiers sont enregistrés dans le répertoire courant, sauf chemin explicite avec -o. Avant une reprise avec -C -, vérifiez que le fichier local correspond bien à la même ressource distante : reprendre une archive différente ne garantit pas un résultat exploitable.
Téléverser avec le format attendu par le serveur
Pour un formulaire HTTP acceptant un fichier, utilisez curl -F "[email protected]" "https://example.com/upload". Le signe @ indique un fichier local ; curl construit le corps multipart/form-data et sa délimitation. Ne définissez pas manuellement cet en-tête sans nécessité.
Pour un transfert direct, curl -T rapport.pdf -u utilisateur "sftp://serveur.example/depot/rapport.pdf" envoie le fichier via SFTP si votre installation prend ce protocole en charge. L’option -T fonctionne aussi avec FTP ou un serveur HTTP acceptant PUT. Préférez SFTP ou FTPS à FTP non chiffré et vérifiez les droits du répertoire distant.
Construire une requête API : paramètres, JSON et méthodes HTTP
Pour ajouter des paramètres GET sans encoder les espaces à la main, utilisez curl -G --data-urlencode "q=serveur linux" "https://example.com/recherche". Avec -G, les données rejoignent l’URL plutôt que le corps de la requête.
Un formulaire classique s’envoie avec curl -d "nom=Alice&actif=true" "https://example.com/utilisateurs". L’option -d déclenche POST et utilise par défaut le type application/x-www-form-urlencoded. Pour une valeur contenant des caractères spéciaux, préférez --data-urlencode.
Envoyer du JSON sans mélanger format et méthode
Une requête JSON peut s’écrire curl -H "Content-Type: application/json" -d '{"nom":"Alice"}' "https://example.com/utilisateurs". L’en-tête décrit le contenu envoyé ; il ne transforme pas automatiquement des données mal formées en JSON valide.
Depuis curl 7.82.0, curl --json @donnees.json "https://example.com/utilisateurs" simplifie l’envoi d’un fichier JSON et ajoute les en-têtes adaptés. Pour modifier la méthode, ajoutez -X PUT ou -X PATCH selon le contrat de l’API. Une suppression peut utiliser curl -X DELETE "https://example.com/utilisateurs/42" : cette commande peut réellement supprimer une ressource.
Pour faciliter le diagnostic, créez une requête jumelle de votre appel de référence : même URL, mêmes données, mais un seul paramètre modifié. Comparez ensuite le statut, les en-têtes et le corps. Ce protocole de comparaison évite d’attribuer à l’authentification une erreur causée, par exemple, par un champ JSON modifié simultanément.
Si jq est installé, curl -sS "https://example.com/api" | jq . rend une réponse JSON plus lisible. Un échec de jq peut toutefois signaler une page HTML reçue à la place du JSON attendu.
Protéger les identifiants, cookies et certificats
Pour une authentification Basic, curl -u alice "https://example.com/prive" demande le mot de passe sans l’inscrire directement dans la commande. Utilisez HTTPS : Basic n’assure pas lui-même le chiffrement des identifiants.
Un token Bearer se transmet avec curl -H "Authorization: Bearer $TOKEN" "https://example.com/api". La variable évite de recopier le secret dans chaque commande, mais ne constitue pas un coffre-fort : selon le système, les arguments du processus peuvent être visibles. Évitez les secrets littéraux dans l’historique, les journaux et les captures d’écran.
Les cookies reçus s’enregistrent avec --cookie-jar cookies.txt, puis se réutilisent avec -b cookies.txt. Protégez ce fichier comme un identifiant de session. Un fichier de configuration chargé avec --config curl.conf mérite les mêmes restrictions d’accès s’il contient des informations sensibles.
Ne banalisez pas -k ou --insecure : cette option désactive la vérification du certificat TLS. Pour une autorité interne, utilisez plutôt --cacert autorite.pem. Si un certificat client est exigé, --cert et --key permettent de fournir les éléments correspondants.
Diagnostiquer une erreur et rendre les scripts fiables
curl -I "https://example.com" effectue une requête HEAD pour obtenir les en-têtes sans le corps. Certains serveurs traitent HEAD différemment de GET ; pour observer une réponse GET complète, utilisez -i. Le mode -v détaille notamment la connexion et les échanges HTTP, mais peut exposer des informations sensibles dans les traces.
Un statut 401 invite à vérifier l’authentification, 403 les autorisations, 404 l’adresse demandée, 429 la limitation des requêtes et 500 le traitement côté serveur. Pour tester un proxy, ajoutez -x "http://proxy.example:8080" ; pour modifier l’agent utilisateur, utilisez -A.
Dans un script, une réponse HTTP d’erreur n’entraîne pas forcément un échec de curl. Cette commande combine contrôle HTTP, délais et diagnostic :
curl --fail-with-body -sS --connect-timeout 5 --max-time 30 --retry 3 -o reponse.json -w 'HTTP=%{http_code} temps=%{time_total}s\n' "https://example.com/api"
-sS masque la progression tout en conservant les erreurs ; --fail-with-body conserve le corps et signale les erreurs HTTP par un code de sortie non nul. Contrôlez ce code dans votre script. Réservez les nouvelles tentatives aux opérations pouvant être répétées sans effet indésirable, surtout lorsqu’un appel crée une ressource.
Pour approfondir une option selon votre version installée, consultez curl --help all ou man curl. Cette vérification évite d’utiliser une fonctionnalité absente sur un serveur plus ancien.