Comando curl in Linux: controllare risposte HTTP e scaricare file

curl richiede o invia dati a un URL: serve per consultare risposte HTTP, chiamare API (interfacce di programmazione delle applicazioni) e scaricare file. Per una normale richiesta HTTP senza opzioni di invio usa GET e scrive il corpo della risposta sullo standard output; lo stato HTTP e il codice di uscita del programma restano due informazioni distinte.

Un trasferimento può terminare con codice di uscita 0 anche se il server risponde 404 o 500. Per trattare gli errori HTTP come fallimenti usa --fail oppure --fail-with-body se vuoi conservare anche il corpo di errore. -L segue i reindirizzamenti e -o sceglie il file di destinazione.

Sintassi e preparazione

curl [options] URL

La riga descrive la sintassi: sostituisci il segnaposto URL e le opzioni, senza copiare le parentesi quadre. Per gli esempi seguenti servono curl installato e accesso HTTPS al sito; example.com è un dominio di esempio e le risposte reali possono cambiare.

Controlla curl --version e man curl sulla macchina interessata: protocolli, funzionalità TLS e opzioni dipendono dalla versione e dalla compilazione. --fail-with-body richiede curl 7.76.0 o successivo. I comandi con /dev/null qui sotto sono per una shell Linux; altri ambienti hanno dispositivi nulli e regole di quoting differenti.

Consultare intestazioni, corpo e file scaricati

Intestazioni di risposta. L'opzione -I invia una richiesta HEAD, che chiede le intestazioni senza scaricare il corpo:

curl -I https://example.com/

Leggi la riga di stato HTTP e le intestazioni restituite. Un server può rifiutare HEAD o trattarla diversamente da GET: un 403 o 405 in questa prova non basta a dichiarare inesistente la pagina. Per controllare con GET mostrando le intestazioni e scartando il corpo puoi usare curl -sS -D - -o /dev/null https://example.com/. Diversamente da HEAD, questa operazione trasferisce il corpo prima di scartarlo.

Corpo e gestione degli errori. Per seguire i reindirizzamenti e rendere gli errori HTTP un fallimento del comando:

curl -fL https://example.com/

Se la risposta finale ha successo, il corpo viene scritto nel terminale; -f non aggiunge automaticamente la riga di stato a quel corpo. Su HTTP 400 o superiore normalmente sopprime il corpo e restituisce il codice di uscita 22. Il manuale segnala eccezioni, specialmente con autenticazione 401 e 407: per una decisione rigorosa controlla anche il codice HTTP atteso.

Salvataggio. Per scrivere il corpo in un file nella directory corrente:

curl -fL -o example.html https://example.com/

Scegli una directory e un nome che non contengano dati da preservare: curl può sovrascrivere un file già presente. Un trasferimento interrotto può lasciare un file parziale. Prima di usare il download controlla il codice di uscita e il contenuto; per software o archivi verifica anche gli eventuali hash o firme pubblicati dal fornitore. Un nome con estensione .html non garantisce da solo il tipo o la correttezza del file.

Leggere lo stato HTTP senza confonderlo con l'esito di curl

Questa richiesta GET scarta il corpo e stampa il codice HTTP:

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

Esempio illustrativo di una risposta con stato 200:

200

-s nasconde il misuratore di avanzamento; -S mantiene visibili i messaggi di errore. -w stampa le informazioni richieste dopo il trasferimento e \n aggiunge una nuova riga. Il codice 200 indica un esito HTTP positivo, ma non prova che la pagina contenga i dati attesi o che un'operazione applicativa sia riuscita.

In questo comando non ci sono né -L né -f: un reindirizzamento può quindi mostrare 301 o 302, e un 404 può accompagnarsi al codice di uscita 0. Aggiungi -L per seguire la destinazione e -f oppure --fail-with-body quando serve la gestione degli errori HTTP. Un valore 000 può indicare che non è stato ottenuto un codice HTTP; conserva il messaggio di errore e il codice di uscita per distinguere problemi di connessione, DNS o TLS.

In Bash puoi leggere il codice di uscita con rc=$? subito dopo curl, prima di eseguire qualsiasi altro comando. Lo stato HTTP stampato da -w non sostituisce questo controllo. Se servono il corpo diagnostico e un errore di processo, scegli --fail-with-body; non combinarlo con -f, perché sono alternative.

In una verifica locale del 3 novembre 2026 con curl 8.19.0 per Windows distribuito con Git e un server HTTP Python 3.12.14, lo stesso endpoint 404 ha restituito codice di uscita 0 senza queste opzioni e 22 con entrambe le alternative: -f ha soppresso il corpo, --fail-with-body lo ha conservato. È una prova del comportamento HTTP locale, non un'esecuzione Linux né una verifica di TLS o di un'API esterna.

Opzioni principali

file e intestazione sono segnaposto. -o minuscolo sceglie un percorso locale; -O maiuscolo ricava il nome dall'URL e non equivale automaticamente al nome dichiarato in Content-Disposition. Anche con -O controlla la destinazione prima del download, perché un file omonimo può essere sovrascritto.

Controlli pratici e precauzioni

1. Verifica prima URL, metodo e destinazione. Per query con caratteri interpretati dalla shell, come &, racchiudi l'intero URL tra virgolette.
2. Se HEAD è rifiutato, riprova con GET e confronta stato e contenuto; non classificare una risposta soltanto dal codice di uscita di curl.
3. Se usi -L, considera anche l'URL finale e il numero di reindirizzamenti. Non inoltrare indiscriminatamente intestazioni sensibili a destinazioni diverse: le intestazioni personalizzate con -H richiedono particolare attenzione.
4. Quando automatizzi, imposta limiti adatti con --connect-timeout per la fase di connessione e --max-time per ogni trasferimento completo. Se abiliti i tentativi automatici con --retry, il contatore di --max-time riparte a ogni tentativo; valuta anche --retry-max-time per limitare la fase dei tentativi. Scegli i valori in base al servizio e gestisci separatamente i fallimenti.

Non collegare direttamente alla shell uno script scaricato da un URL non verificato. Evita token segreti nei comandi salvati nella cronologia o visibili negli elenchi dei processi; oscura segreti e intestazioni sensibili prima di conservare log dettagliati.

Con HTTPS lascia attiva la verifica del certificato. -k la disabilita e non è una soluzione ordinaria agli errori TLS: identifica invece il problema del certificato, del nome del server, dell'orologio o delle autorità fidate. Per i dettagli consulta la documentazione ufficiale sulla verifica dei certificati in curl.

Domande frequenti

Perché curl sembra riuscire anche dopo una risposta 404?

Per impostazione predefinita distingue il trasferimento della risposta dal suo esito HTTP. Un 404 ricevuto correttamente può quindi produrre codice di uscita 0. Usa -f o --fail-with-body quando appropriato e controlla anche lo stato HTTP e il contenuto necessari alla tua applicazione.

Documentazione di riferimento

Il manuale ufficiale di curl descrive opzioni, codici di uscita e requisiti di versione. Confrontalo con la versione installata prima di usare opzioni introdotte di recente o caratteristiche dipendenti dalla compilazione.