Skip to Content
CLIcurl

🌐 curl

Guide de référence pour curl — requêtes HTTP/HTTPS, bodies, headers, authentification, SSL, pipelines, code de sortie.

curl (Client URL) est l’outil CLI universel pour interagir avec n’importe quel service HTTP. Il prend en charge HTTP, HTTPS, FTP, SCP, SFTP et bien plus.

Commandes de base

GET simple

# Télécharge le contenu brut curl https://api.example.com/health # Télécharge et affiche les headers de réponse curl -I https://api.example.com # Télécharge avec les headers d'échange (request + response) curl -v https://api.example.com

POST avec corps JSON

curl -X POST https://api.example.com/users \ -H "Content-Type: application/json" \ -d '{"name": "Arthur", "role": "developer"}'

Autres méthodes HTTP

# PUT curl -X PUT https://api.example.com/users/42 \ -H "Content-Type: application/json" \ -d '{"role": "admin"}' # PATCH curl -X PATCH https://api.example.com/users/42 \ -H "Content-Type: application/json" \ -d '{"role": "admin"}' # DELETE curl -X DELETE https://api.example.com/users/42

Headers personnalisés

# Un seul header curl -H "X-Request-ID: abc123" https://api.example.com # Multiples headers curl -H "Authorization: Bearer ***" \ -H "Accept: application/json" \ -H "X-Tenant-ID: acme" \ https://api.example.com/data

Bodies et formats

JSON

# Corps JSON depuis la ligne de commande curl -X POST https://api.example.com/items \ -H "Content-Type: application/json" \ -d '{"title": "Doc", "tags": ["tech", "infra"]}' # Corps JSON depuis un fichier curl -X POST https://api.example.com/items \ -H "Content-Type: application/json" \ -d @payload.json

Données URL-encoded (formulaires)

curl -X POST https://api.example.com/login \ -d "username=arthur&password=secret"

Multipart (upload de fichier)

curl -X POST https://api.example.com/upload \ -F "file=@rapport.pdf" \ -F "description=Rapport Q2"

Corps XML

curl -X POST https://api.example.com/sync \ -H "Content-Type: application/xml" \ -d '<item><name>test</name></item>'

Authentification

Token Bearer

curl -H "Authorization: Bearer ***" \ https://api.example.com/profile

Basic Auth

# Utilisateur/mot-de-passe (URI-encoded) curl -u arthur:s3cret https://api.example.com/admin # Utilisateur uniquement (prompt pour le mot de passe) curl -u arthur https://api.example.com/admin

Clé API dans un header

curl -H "X-API-Key: ***" \ https://api.example.com/data
# Sauvegarder les cookies reçus curl -c cookies.txt https://api.example.com/login \ -d "user=arthur&pass=s3cret" # Utiliser les cookies sauvegardés curl -b cookies.txt https://api.example.com/dashboard

Envoyer un jeton via l’URL

# Paramètre de requête (utile pour certains Webhooks) curl "https://api.example.com/data?token=***" # Attention : ces URLs sont susceptibles d'être loggées par le proxy.

Éviter d’envoyer des tokens ou mots de passe en clair dans l’URL. Les proxies, logs et historiques navigateur les exposent.

SSL et certificats

Désactiver la vérification (développement uniquement)

# Ignorer l'erreur de certificat auto-signé curl -k https://self-signed.local # Équivalent long curl --insecure https://self-signed.local

Utiliser un certificat client

# Certificat client + clé privée curl --cert client.crt --key client.key \ https://mutual-tls.example.com # Avec un CA personnalisé curl --cacert /etc/ssl/ca-custom.pem \ https://internal.example.com

Forcer HTTPS

# Rejeter si la connexion ne commence pas en HTTPS curl --proto =https https://example.com

Vérifier le certificat d’un serveur

# Affiche les détails du certificat TLS openssl s_client -connect api.example.com:443 -servername api.example.com # Avec curl, vérifier l'expiration du certificat curl -v https://example.com 2>&1 | grep -i "expire"

Codes de statut et indicateurs

# Afficher uniquement le code HTTP de réponse curl -o /dev/null -s -w "%{http_code}" https://api.example.com # Afficher plus d'informations : temps, type de contenu, taille curl -o /dev/null -s -w "\nStatus: %{http_code}\nTime total: %{time_total}s\nSize: %{size_download} bytes\n" \ https://api.example.com # Suivre les redirections et afficher le code final curl -o /dev/null -s -w "%{http_code}" -L https://example.com/old-path

Délais et retry

Timeout

# Timeout total de la connexion (secondes) curl --connect-timeout 10 https://api.example.com # Timeout de lecture (temps max sans donnée) curl --max-time 30 https://api.example.com/slow-endpoint # Les deux combinés curl --connect-timeout 10 --max-time 60 https://api.example.com

Retry automatique (curl 7.53+)

# Réessayer jusqu'à 3 fois avec un délai de 2s entre chaque curl --retry 3 --retry-delay 2 https://api.example.com/unstable # Ne retry que sur les erreurs réseau (pas les codes HTTP) curl --retry 3 --retry-connrefused https://api.example.com # Retry uniquement sur certains codes HTTP curl --retry 3 --retry-on-http-status 502,503,504 \ https://api.example.com

Pipelines et filtrage

Filtrer la sortie JSON

# Formater et filtrer un JSON avec jq curl -s https://api.example.com/users | jq '.[] | select(.role == "admin")' # Extraire un champ spécifique curl -s https://api.example.com/health | jq -r '.version'

Rechercher des chaînes dans la réponse

# grep simple curl -s https://api.example.com/log | grep "ERROR" # grep avec contexte curl -s https://api.example.com/log | grep -B2 -A2 "exception"

Sauvegarder la réponse dans un fichier

# Redirection simple curl -s https://example.com > page.html # Append via le shell curl -s https://example.com/sitemap-part2 >> sitemap.xml

Dépannage

Headers de sécurité (CSP, CORS, HSTS)

# Lister les headers de réponse curl -I https://api.example.com # Vérifier les headers de sécurité courants curl -sI https://example.com | grep -iE "strict-transport|x-frame-options|content-security-policy|x-content-type"

Forcer HTTP 1.1

# Certains serveurs refusent HTTP/2 depuis curl curl --http1.1 https://api.example.com

Alias utiles

Ajouter dans ~/.bashrc ou ~/.zshrc :

# Formater JSON sortant de curl alias curlj='curl -s -H "Accept: application/json" | jq .' # Afficher les headers sans le body alias curlh='curl -sI' # Déboguer une API avec headers alias curl-debug='curl -s -D - -o /dev/null'

curl -v reste le premier réflexe de débogage. Il affiche l’échange complet : DNS, TCP, TLS handshake, headers request/response.

Références