Generatore e costruttore di comandi cURL

Cos'è un comando curl?

# Plain GET — curl defaults to GET
curl https://api.example.com/users

# GET with a Bearer token (auth is just a header)
curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

# POST a JSON body — note the Content-Type header
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

# Multipart file upload — '@' reads the file from disk
curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

Funzionalità principali

Alternative a curl e client HTTP

Esempi di comandi curl

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

curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

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

curl -X POST https://api.example.com/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=ada&password=s3cret'

curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

curl -L -o archive.zip \
  https://example.com/files/archive.zip

curl -u ada:s3cret \
  https://api.example.com/private

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

Come costruire un comando curl

1. 1

   Scegli il metodo HTTP

   Seleziona GET, POST, PUT, PATCH, DELETE, HEAD o OPTIONS. curl usa GET per default; scegliere POST o un altro verbo aggiunge `-X METODO` al comando generato. Oppure tocca un chip preset per impostare il metodo e un corpo corrispondente con un solo clic.

2. 2

   Inserisci l'URL e i parametri di query

   Digita l'URL della richiesta (ad es. `https://api.example.com/users`). Aggiungi i parametri di query come coppie chiave/valore e lo strumento li codifica via URL e aggiunge `?chiave=valore&…` all'URL automaticamente — nessuna codifica manuale necessaria.

3. 3

   Aggiungi intestazioni e autenticazione

   Aggiungi le intestazioni della richiesta come coppie chiave/valore, poi scegli uno schema di autenticazione: None, token Bearer, Basic (username/password) o un'intestazione API key personalizzata. L'intestazione `Authorization` o personalizzata corretta viene generata nel formato esatto che il server si aspetta.

4. 4

   Imposta il corpo della richiesta

   Per POST/PUT/PATCH, scegli un tipo di corpo: incolla JSON grezzo (l'intestazione `Content-Type` viene aggiunta per te), costruisci campi form urlencoded o assembla un upload multipart e imposta qualsiasi campo come file con il prefisso `@`.

5. 5

   Attiva le opzioni

   Attiva i flag necessari — segui reindirizzamenti (`-L`), TLS non sicuro (`-k`), verbose (`-v`), includi intestazioni (`-i`), compresso (`--compressed`), output su file (`-o`), un timeout di connessione o un proxy (`-x`). Ogni toggle aggiorna il comando in tempo reale.

6. 6

   Copia, esporta o reimposta

   Copia il comando completato, usa Esporta .sh per scaricarlo come script, oppure usa Reset per cancellare il modulo. Usa il toggle Multi-riga per passare dall'output su una riga a quello con continuazione prima di copiare.

Errori comuni in curl

# Intendeva un PATCH, ma -d da solo implica POST
curl -d '{"role":"admin"}' \
  https://api.example.com/users/7

# Specifica il verbo esplicitamente
curl -X PATCH -d '{"role":"admin"}' \
  -H 'Content-Type: application/json' \
  https://api.example.com/users/7

# Il server vede urlencoded, non JSON — 400/415
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

# Dichiara il content type JSON
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada"}'

# $name viene espanso dalla shell in una stringa vuota
curl -d "{\"user\":\"$name\"}" \
  https://api.example.com/users

# Le virgolette singole inviano il corpo letteralmente
curl -d '{"user":"$name"}' \
  https://api.example.com/users

# -d trasforma questa in una POST, non una GET
curl -d 'page=2&limit=50' \
  https://api.example.com/users

# La query string nell'URL mantiene la richiesta GET
curl 'https://api.example.com/users?page=2&limit=50'

:: cmd.exe — il backslash non è un carattere di continuazione
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

:: cmd.exe — su una riga, oppure usa ^ per continuare
curl -X POST https://api.example.com/users -d "{\"name\":\"Ada\"}"

# Lo spazio divide l'argomento — curl vede due argomenti
curl https://api.example.com/search?q=hello world

# Codifica lo spazio (o metti tra virgolette l'intero URL)
curl 'https://api.example.com/search?q=hello%20world'

Casi d'uso comuni

Test di REST API

Costruisci e invia richieste a un endpoint REST senza lasciare il terminale: imposta il metodo, incolla un token Bearer, invia un corpo JSON e leggi la risposta. Il modo più veloce per verificare che un'API si comporti correttamente prima di scrivere il codice client.

Riproduzione di richieste dalla documentazione

La documentazione API mostra endpoint e parametri, ma raramente un comando completo pronto da copiare. Compila qui metodo, URL, intestazioni e autenticazione e ottieni un comando curl che funziona così com'è — senza problemi di quoting o intestazioni `Content-Type` mancanti.

Script di smoke-test CI/CD

Genera un comando curl per un health check o uno smoke test post-deploy, poi usa Esporta .sh per inserirlo in una pipeline. Aggiungi `--connect-timeout` e `--max-time` per evitare che un endpoint bloccato blocchi la build, e verifica i codici di stato con `-w`.

Upload e download di file

Assembla un upload `multipart/form-data` con `-F campo=@file`, oppure costruisci un download `-L -o nomefile` che segue i reindirizzamenti verso una CDN. Codifica prima i nomi di file o valori di query complessi con il nostro codificatore URL.

Debug di webhook

Riproduci il payload di un webhook inviando via POST lo stesso corpo JSON che il provider invia, con le intestazioni di firma e `Content-Type` corrette. Riproduci la richiesta esatta in locale per capire perché il tuo handler l'ha rifiutata.

Segnalazioni di bug riproducibili

Incolla un singolo comando curl autonomo in una segnalazione di bug o in una PR in modo che chiunque possa riprodurre la richiesta esatta — metodo, intestazioni, segnaposto di autenticazione e corpo. Molto più chiaro di una descrizione testuale della richiesta.

Apprendimento dei flag curl

Osserva come ogni scelta nel modulo corrisponde a un flag reale — scegli l'autenticazione Basic e guarda apparire `-u`, aggiungi un corpo JSON e guarda l'intestazione `Content-Type` allegarsi. Un modo pratico per imparare la sintassi, abbinato al nostro cheat sheet curl.

Preparazione di una richiesta da convertire in codice

Costruisci e verifica la richiesta come curl prima, poi traducila nel client HTTP della tua app. La scheda Convert in arrivo trasformerà un comando curl incollato in fetch, requests, Go, PHP, Ruby e Node.js — parti da un comando curl che sai funzionare.

Flag e riferimento alla sintassi curl

Quoting ed escaping nella shell

Lo strumento racchiude i valori tra virgolette singole, la forma più sicura nelle shell POSIX perché nulla all'interno di una stringa tra virgolette singole viene espanso. Una virgoletta singola letterale all'interno di un valore viene emessa come sequenza `'\''` (chiudi virgolette, virgoletta escaped, riapri virgolette). Su `cmd.exe` usa le virgolette doppie; Git Bash e WSL eseguono i comandi con virgolette singole generati senza modifiche.

-d vs --data-raw vs --data-binary

`-d`/`--data` rimuove i ritorni a capo e i caratteri di fine riga dal corpo — adatto per coppie `key=value`, con perdita di informazioni per contenuti su più righe. `--data-raw` è uguale ma non tratta un `@` iniziale come nome di file. `--data-binary` invia i byte esattamente come forniti (usa `@file` per caricare il contenuto grezzo di un file). Tutti e tre implicano POST a meno che il metodo non venga sovrascritto.

Multipart (-F) vs urlencoded (-d)

`-F campo=valore` produce `multipart/form-data` con un boundary generato — necessario per upload di file (`-F file=@percorso`) e form misti file/testo. `-d campo=valore` produce `application/x-www-form-urlencoded`, una singola stringa unita da `&`. Non impostare mai `Content-Type` manualmente per multipart; curl calcola il boundary e imposta l'intestazione da solo.

Codifica dell'intestazione di autenticazione

L'autenticazione Bearer invia `Authorization: Bearer ` testualmente (RFC 6750). L'autenticazione Basic con `-u utente:password` viene codificata in Base64 in `Authorization: Basic ` durante la trasmissione — codifica, non cifratura, quindi usa sempre HTTPS. Una API key è qualsiasi intestazione personalizzata richiesta dal servizio, ad es. `X-API-Key: `.

Codifica della query string

I parametri di query aggiunti nel builder vengono percent-encoded e aggiunti come `?chiave=valore&chiave2=valore2`. I caratteri riservati (spazi, `&`, `=`, `#`) vengono escaped in modo che l'URL sia valido. Per i campi del corpo che devono essere codificati, `--data-urlencode` di curl gestisce la codifica al momento della richiesta.

Comportamento dei reindirizzamenti (-L)

Senza `-L`, curl stampa una risposta 301/302 e si ferma. Con `-L` segue l'intestazione `Location` fino all'URL finale. Da notare che curl rimuove l'intestazione `Authorization` quando un reindirizzamento cambia host (comportamento predefinito di sicurezza); usa `--location-trusted` solo quando capisci le implicazioni.

Risposte compresse

`--compressed` aggiunge un'intestazione `Accept-Encoding` che dichiara il supporto a gzip/deflate/brotli e decomprime la risposta in modo trasparente, risparmiando banda. Il corpo decodificato è identico a una richiesta non compressa — si tratta di una pura ottimizzazione del trasferimento, sicura da abilitare nella maggior parte delle chiamate API.

Output: -o vs -O

`-o nomefile` scrive il corpo della risposta in un file con il nome che specifichi; `-O` lo salva con il nome del file remoto ricavato dal percorso URL. Entrambi sopprimono il normale output su stdout. Combinali con `-L` per risolvere i reindirizzamenti verso la risorsa reale prima che il file venga scritto.

Best practice per le richieste curl

Non includere mai segreti nei comandi condivisi

Un comando curl che incolli in una PR, in un ticket o in una chat verrà letto da altri e indicizzato dagli strumenti. Sostituisci token e password con un segnaposto (`YOUR_TOKEN`) o fai riferimento a una variabile d'ambiente (`-H "Authorization: Bearer $API_TOKEN"`). Per credenziali lunghe, curl può leggere un'intestazione da un file con `-H @headerfile` in modo che il segreto non appaia mai nella cronologia della shell.

Preferisci --data-binary @file per payload binari

Quando il corpo è un file i cui byte sono importanti — un'immagine, un payload firmato, JSON in cui gli spazi sono significativi — usa `--data-binary @file` invece di `-d @file`. Il semplice `-d` rimuove i ritorni a capo, corrompendo silenziosamente i contenuti binari e multi-riga. `--data-binary` invia il file esattamente come si trova su disco.

Metti tra virgolette i valori delle intestazioni

Racchiudi sempre i valori di `-H` tra virgolette: `-H 'Content-Type: application/json'`. Senza virgolette, lo spazio dopo i due punti divide l'argomento e curl riceve un'intestazione malformata. Le virgolette singole impediscono anche alla shell di espandere `$`, `*` e altri caratteri speciali all'interno del valore — esattamente quello che emette questo strumento per default.

Usa --compressed per risparmiare banda

Aggiungi `--compressed` alle chiamate API e ai download per richiedere la codifica gzip/brotli e fare in modo che curl decomprima in modo trasparente. Per API che restituiscono molto JSON, questo può ridurre le dimensioni del trasferimento del 70–90% senza alcuna modifica alla risposta che visualizzi — un vantaggio gratuito negli script che interrogano endpoint ripetutamente.

Imposta sempre i timeout negli script

In qualsiasi contesto automatizzato, aggiungi `--connect-timeout` e `--max-time` per evitare che un endpoint lento o bloccato blocchi una pipeline per sempre. Un health check con `--max-time 10` fallisce rapidamente e permette al CI di proseguire. Abbinalo a `--retry N` per assorbire problemi di rete transitori senza rinunciare immediatamente.

Verifica con -v prima di automatizzare

Prima di inserire un comando curl in uno script o in un cron job, eseguilo una volta con `-v` per vedere la riga della richiesta esatta, le intestazioni e l'handshake TLS. È il modo più veloce per individuare un metodo errato, un `Content-Type` mancante o un'intestazione di autenticazione che non è stata allegata — esegui il debug in modo interattivo, poi rimuovi `-v` per la produzione.

Domande frequenti