Linux / Comando curl: requisições HTTP, status e downloads

O comando curl transfere dados de ou para uma URL e permite inspecionar respostas do Protocolo de Transferência de Hipertexto (HTTP), consultar interfaces de programação de aplicações (APIs) e baixar arquivos. Sem uma opção de destino, normalmente escreve o corpo da resposta na saída padrão; o status HTTP e o código de saída do programa são informações diferentes.

Uma transferência pode terminar com código de saída 0 mesmo após receber HTTP 404 ou 500. Para tratar esses estados como falhas em scripts, escolha --fail ou --fail-with-body, conforme a necessidade de guardar o corpo do erro. Use -L para seguir redirecionamentos e -o para escolher um arquivo de saída.

Sintaxe básica e preparação

curl [opções] URL

Os colchetes representam uma parte opcional e não devem ser digitados. Os exemplos abaixo usam HTTPS e consultas de leitura. Coloque uma URL entre aspas se contiver caracteres interpretados pelo shell, como &. Verifique curl --version e man curl na máquina em que vai trabalhar: a versão, os protocolos e os recursos compilados podem variar.

Se o comando não estiver disponível, identifique o pacote da sua distribuição. Para salvar arquivos, trabalhe em uma pasta de testes e confira o nome de destino antes da execução. O domínio example.com é reservado para documentação; sua resposta pública não deve servir de base para monitoramento contínuo de um serviço real.

Exemplos de requisição e download

Consultar cabeçalhos de resposta

A opção -I usa o método HTTP HEAD, que solicita cabeçalhos sem o corpo da representação:

curl -I https://example.com/

Observe a linha de status e os campos relevantes, como Content-Type e, em um redirecionamento, Location. O resultado de HEAD pode diferir do de GET. Se o servidor negar HEAD, por exemplo com 405 Method Not Allowed, faça uma consulta GET antes de concluir que a URL não existe. Não substitua -I apenas por -X HEAD: a opção dedicada também ajusta como o curl espera a resposta.

Obter o corpo e seguir redirecionamentos

curl -fL https://example.com/

Nessa combinação, -f pede falha para erros HTTP e -L segue o endereço indicado pelo servidor. O corpo final aparece no terminal; os cabeçalhos e o status não são impressos automaticamente como uma linha de resumo. Para obter somente o número do status, use o exemplo da seção seguinte.

Ao seguir redirecionamentos, verifique se o destino é o esperado, principalmente em chamadas autenticadas. Cabeçalhos personalizados podem acompanhar novos pedidos; não presuma que qualquer segredo em -H fica restrito ao primeiro destino. O manual detalha as proteções específicas de Authorization e Cookie e o efeito de opções que permitem encaminhar credenciais a outras origens.

Salvar a resposta em arquivo

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

O corpo vai para example.html na pasta atual. Esse nome não comprova que o conteúdo seja HTML: examine o tipo e o conteúdo recebido. O destino pode ser sobrescrito; escolha um nome novo para preservar arquivos existentes. Uma falha durante a transferência também pode deixar um arquivo parcial, portanto confira o código de saída antes de usar o download.

Para excluir automaticamente um arquivo de saída quando a transferência falhar, existe --remove-on-error, disponível desde o curl 7.83.0. Use-a apenas com um destino que possa ser removido e confirme a disponibilidade na versão instalada. Não execute o conteúdo baixado apenas porque o download terminou.

Mostrar somente o status HTTP

Este comando descarta o corpo e imprime o número do status ao fim da transferência:

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

Exemplo de saída para uma resposta HTTP bem-sucedida:

200

A combinação -sS oculta o medidor de progresso, mas mantém as mensagens de erro. -o /dev/null descarta o corpo recebido no Linux, e -w escreve o valor de http_code; \n acrescenta uma quebra de linha. O corpo ainda é transferido: descartar a saída não transforma GET em HEAD nem evita o tráfego do download.

O número 200 é um status HTTP de sucesso, mas não comprova que o conteúdo seja o esperado. Uma página de login ou de desafio automático também pode responder 200. Verifique o corpo quando o objetivo for validar uma página ou uma resposta de API.

Esse comando não inclui -f nem -L: um HTTP 404 pode ser impresso com saída do processo igual a 0, e um redirecionamento pode aparecer como 301 ou 302 em vez do status do destino final. Acrescente as opções de que a sua verificação precisa; não interprete automaticamente “diferente de 200” como uma falha de transporte.

Se não houver um status HTTP disponível, o formato pode mostrar 000. Esse valor não é um status enviado por um servidor HTTP; leia também a mensagem de erro e o código de saída para distinguir falhas de resolução, conexão ou verificação de certificados TLS (Transport Layer Security, segurança da camada de transporte).

Em Bash, consulte echo $? imediatamente depois do comando para ver seu código de saída; outro comando já substituirá esse valor. O caminho /dev/null e as aspas dos exemplos seguem o ambiente de shell indicado. No Windows nativo, o destino de descarte e as regras do shell podem ser diferentes.

Opções principais e diferenças importantes

O nome de -O vem da URL, não automaticamente de um cabeçalho Content-Disposition. A opção adicional -J muda esse comportamento; não a confunda com -O sozinho. Para o exemplo que salva example.html, o nome local é escolhido explicitamente por -o.

Tratar falhas em scripts

1. Defina o que significa sucesso: obter uma resposta, receber um status HTTP aceito ou validar o conteúdo são verificações distintas.
2. Use -f quando não precisar do corpo dos erros HTTP. Se o corpo trouxer um diagnóstico necessário, use --fail-with-body, disponível desde 7.76.0. Não combine as duas opções.
3. Confira o código de saída imediatamente, além do status HTTP. O manual registra limitações de --fail, especialmente em situações de autenticação, como 401 e 407; para regras rigorosas, examine explicitamente o status que a aplicação aceita.
4. Estabeleça limites de espera para rotinas automáticas. --connect-timeout limita a fase de conexão e --max-time, a transferência. Com tentativas automáticas, o limite de transferência pode reiniciar a cada tentativa; avalie também a política de repetição.
5. Em downloads, só use o arquivo depois de verificar o resultado. Preserve a versão anterior em um destino separado quando ela for necessária e não trate um arquivo parcial como uma atualização concluída.

Na verificação de 29 de outubro de 2026, o curl 8.19.0 do Git for Windows, no Windows 11, recebeu 200 de example.com e salvou a página com o título “Example Domain”. Um servidor temporário de teste em loopback permitiu comparar respostas controladas: para 404, o padrão terminou com saída 0 e corpo; -f terminou com 22 sem o corpo; --fail-with-body terminou com 22 mantendo o corpo. A comparação também confirmou 302 sem seguir, 200 após -L, e HEAD 405 seguido de GET 200 no mesmo caminho de teste.

Esses testes usaram limites de conexão e transferência e não desativaram a verificação de certificados. O exemplo de /dev/null foi executado no Git Bash chamando o curl do Windows; isso não é uma execução nativa no Linux. O servidor de teste foi encerrado após a comparação. A resposta pública e o suporte a recursos dependem da versão e do ambiente.

Cuidados com comandos e dados sensíveis

Não conecte um script de uma URL desconhecida diretamente ao shell. Primeiro verifique a origem, examine o conteúdo e siga o procedimento de instalação da fonte responsável. O sucesso do HTTP não atesta que um programa baixado seja confiável.

Tokens de autenticação escritos na linha de comando podem aparecer no histórico ou na lista de processos. Cabeçalhos, cookies e saídas de -v ou de rastreamento também podem conter segredos: remova-os antes de guardar ou compartilhar logs. Escolha o método de fornecimento de credenciais conforme a documentação do serviço e controle o acesso aos arquivos que as contêm.

A opção -k desativa a verificação de certificados TLS e não deve ser usada como correção habitual para um erro de certificado. Confira o nome da URL, a validade e a cadeia de confiança e use a configuração de certificados apropriada ao ambiente. Um 403, 405 ou bloqueio automatizado também não autoriza presumir que o conteúdo foi verificado: registre a limitação e confira o método e o acesso permitido.

Pergunta frequente

Por que o curl parece ter sucesso ao receber um HTTP 404?

Porque o código de saída padrão avalia a transferência, enquanto 404 é um status da resposta HTTP. Para tratar erros HTTP como falha, use -f ou --fail-with-body, conforme precise ou não do corpo, e verifique também o status e o conteúdo exigidos pela aplicação.

Documentação oficial

Consulte o manual oficial do curl para confirmar opções, códigos de saída, diferenças entre versões e detalhes de redirecionamentos e autenticação.