Um comando curl tem três partes: o nome do programa (curl), zero ou mais opções e uma URL de destino. Antes que o curl veja qualquer uma delas, o shell quebra a linha em palavras e remove uma camada de aspas.
As aspas importam porque o corpo (body) e os headers da requisição têm espaços e caracteres especiais. Aspas simples são literais: tudo o que está entre elas passa intacto, e por isso corpos em JSON costumam vir entre aspas simples. Aspas duplas deixam o shell expandir variáveis e interpretar alguns escapes com barra invertida (backslash). Uma barra invertida no fim da linha é uma continuação de linha: ela junta a linha seguinte à atual, e é assim que a opção "Copy as cURL" ("Copiar como cURL", nas interfaces em português) gera comandos legíveis em várias linhas.
As opções têm uma forma curta e uma longa. As flags curtas são um traço e uma letra (-X, -H, -d); as longas são dois traços e uma palavra (--request, --header, --data). Flags curtas podem ser agrupadas: -sSL é o mesmo que -s -S -L. Uma flag que recebe valor pode vir com o valor colado, sem espaço, então -XPOST significa -X POST, o que engana quem lê com pressa.
O que não é opção nem valor de opção é a URL. Se o esquema estiver faltando, o curl tenta adivinhar: o padrão é HTTP, e ele assume para um host que começa com ftp..
Leia na ordem em que a requisição é montada, não na ordem em que foi digitada
As flags de um comando curl podem aparecer em qualquer ordem, e isso quer dizer que a sequência escrita na linha não tem nada a ver com a sequência do que acontece. Ler da esquerda para a direita é ler os hábitos de digitação de quem escreveu o comando.
A ordem que importa é a da própria requisição: método, depois URL, depois headers, depois corpo, depois o que acontece com a resposta. Remontar o comando nessa ordem transforma uma linha comprida em cinco perguntas curtas e deixa evidente a peça que falta: um -d sem Content-Type, um -H que repete algo que o curl já define sozinho, uma flag de redirecionamento que muda o que o comando inteiro faz.
Se você não consegue recontar o comando nessa ordem, é porque ainda não terminou de lê-lo, e isso importa principalmente quando o comando veio de outra pessoa e você está prestes a executá-lo.
Esta série, em ordem
Este artigo abre a série curl, flag por flag. Ele mostra como o shell quebra a linha antes de o curl vê-la; os artigos seguintes leem a requisição que o comando monta, na ordem em que ela é montada (método, corpo, headers e credenciais), avaliam a postura de segurança dela, traduzem o comando para o navegador e terminam com tudo o que o curl fala além do HTTP.
- Como o curl infere o método HTTP. Por que um corpo implica POST, -I implica HEAD e -G força GET, e por que um -X explícito sempre prevalece.
- Flags de dados do curl e a armadilha do Content-Type. As formas de incluir um corpo na requisição, e a armadilha: -d envia os dados codificados como formulário, não como JSON.
- Headers, autenticação e cookies no curl. -H, -u, um bearer token enviado como header comum, e -b e -c para cookies: tudo o que identifica a requisição.
- Flags do curl que mudam a postura de segurança. -k, http sem criptografia e credenciais na URL: as flags que vale ler antes de rodar ou compartilhar um comando.
- Como traduzir curl para fetch(). A mesma requisição no fetch() do navegador, e as diferenças que pedem cuidado: o Content-Type de formulário, os cookies, a verificação de TLS.
- Os 27 protocolos que o curl fala. FTP, , , , , , (Lightweight Directory Access Protocol) e as relíquias: os 27 esquemas de URL que o curl fala hoje.