curl

redes

Flags essenciais

Flag	O que faz
`-s`	Silencioso (sem barra de progresso)
`-S`	Mostra erro mesmo com `-s`
`-v` / `-vvv`	Detalhes da conexão, TLS e cabeçalhos
`-i`	Inclui cabeçalhos na saída
`-I`	Só cabeçalhos (`HEAD`)
`-L`	Segue redirecionamento
`-o arquivo` / `-O`	Salva em arquivo
`-f`	Falha (exit ≠ 0) em erro HTTP — essencial em script
`--max-time 10`	Tempo total máximo
`--connect-timeout 3`	Tempo máximo para conectar
`-4` / `-6`	Força IPv4 / IPv6

Em script, o conjunto padrão é curl -fsSL.

Métodos e corpo

curl -X POST https://api.exemplo.com.br/pedidos \
  -H 'Content-Type: application/json' \
  -d '{"item":"abc","quantidade":2}'

curl -X POST -d @pedido.json -H 'Content-Type: application/json' https://api/...
curl -X PUT --data-raw 'texto puro' https://api/...
curl -X DELETE https://api.exemplo.com.br/pedidos/42
curl -F "[email protected]" -F "tipo=fiscal" https://api/upload
curl -G -d "pagina=2" -d "limite=50" https://api/...     # query string

Cabeçalhos e autenticação

curl -H 'Authorization: Bearer $TOKEN' https://api/...
curl -H 'X-Request-Id: teste-123' https://api/...
curl -u usuario:senha https://api/...            # básica
curl --oauth2-bearer "$TOKEN" https://api/...
curl -b 'sessao=abc' -c cookies.txt https://api/...   # envia e salva cookies
curl -H 'Accept-Encoding: gzip' --compressed https://api/...

Evite senha na linha de comando: ela fica no histórico do shell e na lista de processos. Prefira --netrc ou variável de ambiente.

TLS e certificados

curl -v https://host                     # mostra a negociação TLS
curl --cacert ca-interna.pem https://host
curl --cert cliente.pem --key cliente.key https://host   # mTLS
curl -k https://host                     # ignora validação — só para diagnóstico
curl --resolve host:443:10.0.0.5 https://host/    # testa um backend específico

--resolve é a ferramenta certa para testar um servidor antes de mudar o DNS: o certificado continua sendo validado para o nome real.

Tempo de resposta detalhado

É a receita que mais resolve discussões sobre “está lento”:

curl -s -o /dev/null -w '
  dns:      %{time_namelookup}s
  conexao:  %{time_connect}s
  tls:      %{time_appconnect}s
  primeiro: %{time_starttransfer}s
  total:    %{time_total}s
  codigo:   %{http_code}
  tamanho:  %{size_download} bytes
' https://api.exemplo.com.br/health

Leitura dos números: DNS alto → resolvedor; conexão alta → rede ou fila de aceitação; TLS alto → handshake ou cadeia; starttransfer alto → o servidor demorou para processar (este é o mais comum).

Para monitorar continuamente, junte com watch ou um laço com sleep.

Repetição e resiliência

curl --retry 3 --retry-delay 2 --retry-max-time 30 https://api/...
curl --retry 5 --retry-connrefused https://api/...     # tenta também em conexão recusada
curl -C - -O https://exemplo.com/arquivo-grande.tar    # retoma download

Use retry apenas em operação idempotente.

Diagnóstico em cluster

# de dentro do cluster, testando o Service
kubectl run curl --rm -it --image=curlimages/curl -n loja -- \
  curl -sv http://pedidos.loja.svc.cluster.local/health

# testando um Pod específico
kubectl exec -it diag -n loja -- curl -s http://10.1.2.3:8080/readyz

# HTTP/2 e HTTP/3
curl --http2 -I https://host
curl --http3 -I https://host      # exige build com suporte

Receitas

# só o código de status
curl -s -o /dev/null -w '%{http_code}\n' https://host/health

# API com jq
curl -s https://api/pedidos | jq '.items[] | {id, status}'

# cabeçalhos de cache
curl -sI https://cdn.exemplo.com.br/app.js | grep -iE 'cache-control|age|x-cache|etag'

# seguir redirecionamentos mostrando cada salto
curl -sIL https://exemplo.com.br | grep -E '^(HTTP|location)'

# medir p50 improvisado (20 amostras)
for i in $(seq 20); do
  curl -s -o /dev/null -w '%{time_total}\n' https://api/health
done | sort -n | awk '{a[NR]=$1} END {print "mediana:", a[int(NR/2)]}'

Códigos de saída úteis

Código	Significado
0	Sucesso
6	Não resolveu o host
7	Falha ao conectar
22	Erro HTTP (com `-f`)
28	Timeout
35	Erro de handshake TLS
51	Certificado do servidor não verificado
60	Problema no certificado da CA

Pegadinhas

Sem -f, o curl sai com 0 mesmo em 500 — script “funciona” com o serviço quebrado.
-k desabilita a validação: nunca em produção nem em script permanente.
Sem -L, redirecionamento não é seguido e você recebe 301 achando que é erro.
Aspas simples em -d no PowerShell se comportam de outro jeito; atenção ao shell.
-X POST combinado com -L pode virar GET no salto; use --post301/302/303 se precisar preservar.
Cabeçalho com variável não expandida (aspas simples no bash) envia o texto literal.