Gerador e Construtor de Comandos cURL

O que é um 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'

Funcionalidades Principais

Alternativas ao curl e Clientes HTTP

Exemplos de Comando 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

Como Construir um Comando curl

1. 1

   Escolha o método HTTP

   Selecione GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS. O curl usa GET por padrão; escolher POST ou outro verbo adiciona -X METHOD ao comando gerado. Ou toque em um chip de preset para definir o método e um corpo correspondente com um clique.

2. 2

   Insira a URL e os parâmetros de consulta

   Digite a URL da requisição (ex.: https://api.example.com/users). Adicione parâmetros de consulta como pares chave/valor e a ferramenta os codifica na URL e anexa ?key=value&… automaticamente — sem codificação manual necessária.

3. 3

   Adicione cabeçalhos e autenticação

   Adicione cabeçalhos de requisição como pares chave/valor, depois escolha um esquema de auth: Nenhum, Bearer token, Basic (usuário/senha) ou um cabeçalho de API-key personalizado. O cabeçalho Authorization ou personalizado correto é gerado no formato exato que o servidor espera.

4. 4

   Defina o corpo da requisição

   Para POST/PUT/PATCH, escolha um tipo de corpo: cole JSON bruto (o cabeçalho Content-Type é adicionado para você), construa campos de formulário urlencoded, ou monte um upload multipart e alterne qualquer campo para um arquivo com o prefixo @.

5. 5

   Ative as opções

   Ative os flags necessários — seguir redirecionamentos (-L), TLS inseguro (-k), verbose (-v), incluir cabeçalhos (-i), comprimido (--compressed), gravar em arquivo (-o), um timeout de conexão ou um proxy (-x). Cada ativação atualiza o comando ao vivo.

6. 6

   Copie, exporte ou resete

   Copie o comando finalizado, Exporte .sh para baixá-lo como script, ou Resete para limpar o formulário. Use o botão Multilinha para alternar entre saída de linha única e multilinha com continuação antes de copiar.

Erros Comuns no curl

# Pretendia um PATCH, mas -d sozinho implica POST
curl -d '{"role":"admin"}' \
  https://api.example.com/users/7

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

# O servidor vê urlencoded, não JSON — 400/415
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

# Declare o tipo de conteúdo JSON
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada"}'

# $name é expandido pelo shell para string vazia
curl -d "{\"user\":\"$name\"}" \
  https://api.example.com/users

# Aspas simples enviam o corpo literalmente
curl -d '{"user":"$name"}' \
  https://api.example.com/users

# -d transforma isso em POST, não GET
curl -d 'page=2&limit=50' \
  https://api.example.com/users

# Query string na URL mantém como GET
curl 'https://api.example.com/users?page=2&limit=50'

:: cmd.exe — barra invertida não é char de continuação
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

:: cmd.exe — uma linha, ou use ^ para continuar
curl -X POST https://api.example.com/users -d "{\"name\":\"Ada\"}"

# Espaço divide o argumento — curl vê dois args
curl https://api.example.com/search?q=hello world

# Codifique o espaço (ou coloque aspas na URL inteira)
curl 'https://api.example.com/search?q=hello%20world'

Casos de Uso Comuns

Teste de API REST

Construa e dispare requisições contra um endpoint REST sem sair do terminal: defina o método, cole um Bearer token, envie um corpo JSON e leia a resposta. A forma mais rápida de confirmar que uma API se comporta antes de escrever o código do cliente.

Reproduzir uma Requisição da Documentação

A documentação de API mostra endpoints e parâmetros, mas raramente um comando completo pronto para copiar. Preencha o método, URL, cabeçalhos e auth aqui e obtenha um comando curl que executa como está — sem lutar com aspas ou cabeçalhos Content-Type ausentes.

Scripts de Smoke-Test de CI/CD

Gere um comando curl para uma verificação de saúde ou smoke test pós-deploy, depois Exporte .sh para inserir em um pipeline. Adicione --connect-timeout e --max-time para que um endpoint travado não bloqueie o build, e verifique códigos de status com -w.

Upload e Download de Arquivo

Monte um upload multipart/form-data com -F field=@file, ou construa um download -L -o filename que segue redirecionamentos para um CDN. Codifique nomes de arquivo ou valores de consulta difíceis primeiro com nosso codificador de URL.

Depuração de Webhooks

Reproduza um payload de webhook fazendo POST do mesmo corpo JSON que o provedor envia, com os cabeçalhos de assinatura e Content-Type corretos. Reproduza a requisição exata localmente para depurar por que seu handler a rejeitou.

Relatórios de Bug Reproduzíveis

Cole um único comando curl autocontido num relatório de bug ou PR para que qualquer pessoa possa reproduzir a requisição exata — método, cabeçalhos, placeholder de auth e corpo. Muito mais claro do que descrever a requisição em prosa.

Aprender Flags do curl

Veja como cada escolha no formulário mapeia para um flag real — escolha Basic auth e veja -u aparecer, adicione um corpo JSON e veja o cabeçalho Content-Type ser anexado. Uma forma prática de aprender a sintaxe, combinada com nosso guia curl.

Preparar uma Requisição para Converter para Código

Construa e verifique a requisição como curl primeiro, depois traduza para o cliente HTTP do seu aplicativo. A aba Converter que está chegando transformará um comando curl colado em fetch, requests, Go, PHP, Ruby e Node.js — comece a partir de um comando curl que você sabe que funciona.

Flags e Referência de Sintaxe curl

Aspas e Escape no Shell

A ferramenta envolve valores em aspas simples, a forma mais segura em shells POSIX porque nada dentro de uma string com aspas simples é expandido. Uma aspa simples literal dentro de um valor é emitida como a sequência '\'' (fechar aspas, aspa escapada, reabrir aspas). No cmd.exe use aspas duplas; o Git Bash e o WSL executam os comandos com aspas simples gerados sem modificações.

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

-d/--data remove newlines e carriage returns do corpo — adequado para pares key=value, com perda para conteúdo multilinha. --data-raw é igual mas não trata um @ inicial como nome de arquivo. --data-binary envia os bytes exatamente como fornecidos (use @file para fazer upload do conteúdo bruto do arquivo). Os três implicam POST a menos que o método seja sobrescrito.

Multipart (-F) vs URL-encoded (-d)

-F field=value produz multipart/form-data com um boundary gerado — necessário para uploads de arquivo (-F file=@path) e formulários mistos de arquivo/texto. -d field=value produz application/x-www-form-urlencoded, uma única string unida por &. Nunca defina Content-Type manualmente para multipart; o curl calcula o boundary e define o cabeçalho automaticamente.

Codificação do Cabeçalho de Auth

Bearer auth envia Authorization: Bearer <token> literalmente (RFC 6750). Basic auth de -u user:pass é codificado em Base64 como Authorization: Basic <base64> na transmissão — codificação, não criptografia, portanto use HTTPS. Uma API key é qualquer cabeçalho personalizado que o serviço requer, ex. X-API-Key: <value>.

Codificação da Query String

Parâmetros de consulta adicionados no construtor são codificados em percent e anexados como ?key=value&key2=value2. Caracteres reservados (espaços, &, =, #) são escapados para que a URL seja válida. Para campos de corpo que precisam ser codificados, o próprio --data-urlencode do curl lida com a codificação no momento da requisição.

Comportamento de Redirecionamento (-L)

Sem -L, o curl imprime uma resposta 301/302 e para. Com -L ele segue o cabeçalho Location até a URL final. Observe que o curl descarta o cabeçalho Authorization quando um redirecionamento cruza para um host diferente (um padrão de segurança); use --location-trusted apenas quando você entende as implicações.

Respostas Comprimidas

--compressed adiciona um cabeçalho Accept-Encoding anunciando suporte a gzip/deflate/brotli e descomprime a resposta de forma transparente, economizando largura de banda. O corpo decodificado é idêntico a uma requisição sem compressão — puramente uma otimização de transferência, seguro para ativar na maioria das chamadas de API.

Saída: -o vs -O

-o filename grava o corpo da resposta em um arquivo que você nomeia; -O salva com o nome de arquivo remoto do caminho da URL. Ambos suprimem o dump normal para stdout. Combine com -L para que os redirecionamentos resolvam para o asset real antes do arquivo ser gravado.

Boas Práticas para Requisições curl

Nunca Codifique Segredos em Comandos Compartilhados

Um comando curl que você cola num PR, ticket ou chat será lido por outros e indexado por ferramentas. Substitua tokens e senhas por um placeholder (YOUR_TOKEN) ou referencie uma variável de ambiente (-H "Authorization: Bearer $API_TOKEN"). Para credenciais longas, o curl pode ler um cabeçalho de um arquivo com -H @headerfile para que o segredo nunca apareça no histórico do shell.

Prefira --data-binary @file para Payloads Binários

Quando o corpo é um arquivo cujos bytes importam — uma imagem, um payload assinado, JSON onde o espaço em branco é significativo — use --data-binary @file em vez de -d @file. O -d simples remove newlines e carriage returns, corrompendo silenciosamente conteúdo binário e multilinha. --data-binary envia o arquivo exatamente como está no disco.

Coloque Aspas nos Valores de Cabeçalho

Sempre envolva valores -H entre aspas: -H 'Content-Type: application/json'. Sem aspas, o espaço após os dois pontos divide o argumento e o curl vê um cabeçalho malformado. Aspas simples também impedem que o shell expanda $, * e outros caracteres especiais dentro do valor — exatamente o que esta ferramenta emite por padrão.

Use --compressed para Economizar Largura de Banda

Adicione --compressed em chamadas de API e downloads para solicitar codificação gzip/brotli e fazer o curl descomprimir de forma transparente. Para APIs com muito JSON, isso pode reduzir o tamanho da transferência em 70–90% sem nenhuma mudança na resposta que você vê — um ganho gratuito em scripts que consultam endpoints repetidamente.

Defina Timeouts em Scripts

Em qualquer contexto automatizado, adicione --connect-timeout e --max-time para que um endpoint lento ou travado não bloqueie um pipeline para sempre. Uma verificação de saúde com --max-time 10 falha rapidamente e permite que seu CI avance. Combine com --retry N para absorver problemas transitórios de rede sem desistir imediatamente.

Verifique com -v Antes de Automatizar

Antes de incorporar um comando curl em um script ou cron job, execute-o uma vez com -v para ver a linha de requisição exata, cabeçalhos e handshake TLS. É a forma mais rápida de detectar um método errado, um Content-Type ausente ou um cabeçalho de auth que não foi anexado — depure interativamente, depois remova -v para produção.

Perguntas Frequentes