Comando curl: como testar sites e APIs pela VPS

Aprenda o comando curl para ver se um site responde, conferir cabeçalhos, baixar arquivos, chamar APIs e entender os códigos de saída.

Por Redação Eleven Host · @robson.direitodigital · 1 de novembro de 2026 · 9 min de leitura

O comando curl faz requisições a endereços da web pelo terminal. Serve para ver se um site responde, conferir os cabeçalhos da resposta e chamar APIs sem abrir o navegador.

Uma dúvida comum é saber se o site está respondendo. Este guia parte dessa pergunta, passa por baixar arquivos e chamar uma API, e termina nos códigos de saída que o curl devolve quando algo falha. Os fatos vêm da página de manual do curl e do pacote do Ubuntu 24.04; os endereços dos exemplos são fictícios.

O que é o curl e como instalar

Segundo o pacote do Ubuntu, o curl é uma "command line tool for transferring data with URL syntax", isto é, uma ferramenta de linha de comando para transferir dados usando endereços. Num terminal de servidor, como o de uma VPS, ela serve para falar com um site ou uma API.

O pacote se chama curl. Se ele não estiver instalado, em sistemas com apt, como o Ubuntu, o comando comum é este:

sudo apt install curl

No Ubuntu 24.04 (noble), o pacote é o curl 8.5.0. A forma geral de uso é o comando seguido do endereço. Cada opção abaixo muda o que o curl mostra ou faz com a resposta.

Ver se o site responde: -I, -i, -L e -w

A opção -I (--head) busca só os cabeçalhos. A documentação explica que servidores HTTP têm o comando HEAD, que devolve apenas o cabeçalho do documento.

curl -I https://exemplo.com

Se você quer o cabeçalho junto com o corpo da página, use -i. No Ubuntu 24.04 o nome longo é --include: "Include the HTTP response headers in the output".

curl -i https://exemplo.com

Um detalhe de versão: na documentação mais nova do curl, essa opção aparece como --show-headers, e o texto avisa que ela se chamava --include antes da versão 8.10.0. A forma curta -i é a mesma nos dois casos.

Quando o servidor informa que a página mudou de lugar (cabeçalho Location e código 3XX), a opção -L (--location) faz o curl refazer a requisição no novo lugar. Este exemplo segue o redirecionamento e grava o resultado em um arquivo:

curl -L -o pagina.html https://exemplo.com

Para olhar só o código numérico da resposta, a opção -w (--write-out) mostra informação depois da transferência. As variáveis usam o formato %{nome}, e duas delas servem aqui: http_code, o código de resposta da última transferência, e time_total, o tempo total da operação em segundos. Um comando montado com as opções documentadas:

curl -s -o /dev/null -w "%{http_code} %{time_total}\n" https://exemplo.com

O -s silencia o medidor de progresso, e o -o /dev/null joga o corpo da página fora, para sobrar só a linha com o código e o tempo. O /dev/null não é uma opção do curl.

Quer conhecer a VPS da Eleven Host? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver os planos de VPS

Baixar arquivos: -o, -O e -C

Duas opções mandam o resultado para um arquivo. A -o (--output) grava em um arquivo com o nome que você escolher, e a -O (--remote-name) grava em um arquivo com o mesmo nome do arquivo remoto. A documentação explica que só a parte do arquivo é usada e o caminho é cortado.

curl -O https://exemplo.com/arquivo.tar.gz

Se o download for interrompido, a opção -C (--continue-at) retoma a transferência a partir de um ponto. A documentação diz que -C - instrui o curl a descobrir sozinho onde e como retomar. Um exemplo montado com as opções documentadas:

curl -C - -O https://exemplo.com/arquivo.tar.gz

Para limitar o tempo de cada transferência, use -m (--max-time), que define o tempo máximo em segundos que você permite para cada transferência.

Chamar uma API: -X, -H, -d, --json e -u

Para falar com uma API, você precisa de método, cabeçalhos e dados. A opção -X (--request) muda o método da requisição. A -H (--header) acrescenta um cabeçalho extra aos cabeçalhos normais. A -d (--data) envia os dados ao servidor.

Uma observação sobre o -d: em HTTP ele usa POST, como um navegador faz ao enviar um formulário, e passa os dados com o tipo application/x-www-form-urlencoded. Por isso, para uma API que espera JSON, o exemplo acrescenta o cabeçalho Content-Type com -H:

curl -X POST -H "Content-Type: application/json" -d '{"nome":"teste"}' https://exemplo.com/api

Como o -d já usa POST, o -X POST aqui deixa o método explícito. Esse comando é um exemplo montado com as opções documentadas, e não um comando copiado da documentação.

Existe um atalho: a opção --json envia os dados em um POST e funciona como atalho para três opções, os dados mais os cabeçalhos Content-Type e Accept com application/json. Ela foi adicionada na versão 7.82.0 do curl, e o curl 8.5.0 do Ubuntu 24.04 já a tem. Em versões anteriores à 7.82.0, use a forma com -H e -d.

curl --json '{"nome":"teste"}' https://exemplo.com/api

Para APIs que pedem autenticação, a opção -u (--user) especifica o usuário e a senha para a autenticação no servidor.

curl -u usuario_teste https://exemplo.com/api

Uma dica nossa, e não da documentação: evite escrever a senha direto no comando, porque o terminal guarda o que você digita no histórico do shell.

Ver o que acontece por dentro: -v, -s e -S

Quando a resposta não faz sentido, a opção -v (--verbose) faz o curl mostrar informação detalhada da operação. A documentação explica que as linhas do modo detalhado ganham um prefixo: o sinal > marca os cabeçalhos enviados pelo curl, e o sinal < marca os cabeçalhos recebidos.

curl -v https://exemplo.com

Em scripts, o contrário é útil: menos barulho. A opção -s (--silent) ativa o modo silencioso e esconde o medidor de progresso. No Ubuntu 24.04, a página de manual diz que ela também esconde as mensagens de erro. Para ver o erro mesmo no modo silencioso, junte a opção -S (--show-error), que, usada com -s, faz o curl mostrar uma mensagem de erro se falhar.

Há ainda a opção -f (--fail), que falha com o código de saída 22 e sem corpo de resposta quando o servidor devolve um código HTTP 400 ou maior. A própria documentação avisa que esse método "is not fail-safe", isto é, ele não é à prova de falhas, e que há ocasiões em que respostas sem sucesso passam, como no caso de autenticação. Um exemplo que junta as opções:

curl -sS -f --max-time 10 https://exemplo.com/api/status

Esse comando é um exemplo montado com opções documentadas, útil para um script que precisa avisar quando a chamada falha.

Testar o site antes do DNS: --resolve

Numa migração, o domínio ainda aponta para o servidor antigo, mas você quer ver como o site responde no servidor novo. A opção --resolve fornece um endereço personalizado para um par de host e porta. O formato é host:porta:endereço. A documentação traz este exemplo, e aqui o endereço foi trocado por um de documentação, o 203.0.113.10:

curl --resolve exemplo.com:443:203.0.113.10 https://exemplo.com

Assim o curl pede o endereço https://exemplo.com ao servidor indicado, sem depender do que o DNS responde no momento. Para conferir o que o DNS responde de fato, o guia dig e nslookup: como consultar o DNS de um domínio mostra as consultas.

Erros comuns pelos códigos de saída

Quando o curl falha, ele termina com um código de saída. A seção EXIT CODES da documentação lista vários, e este guia trata de seis deles. No shell, a variável $? guarda o código do último comando.

• 6: "Could not resolve host". O servidor remoto informado não pôde ser resolvido. Confira o nome digitado e o DNS.
• 7: "Failed to connect to host". O curl não conseguiu conectar. O guia Portas abertas no Linux: como ver com ss e lsof na VPS ajuda a ver se algo escuta na porta.
• 22: "HTTP page not retrieved". Aparece com -f, quando o servidor devolve erro HTTP 400 ou maior.
• 28: "Operation timeout". O tempo limite definido foi atingido.
• 35: "SSL connect error". O handshake SSL falhou.
• 60: "Peer certificate cannot be authenticated with known CA certificates". O certificado do servidor não pôde ser validado.

O código 60 merece atenção. A opção -k (--insecure) faz o curl pular a verificação do certificado. A documentação é direta: "using this option makes the transfer insecure", e ela pode fazer o curl confiar em informação de servidores maliciosos. Por isso, o -k não é solução para o erro de certificado: ele só esconde o problema. O caminho certo é descobrir por que o certificado não valida.

Está escolhendo uma VPS? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Conhecer a VPS

Perguntas frequentes

Para que serve o comando curl?

Ele faz requisições a endereços da web pelo terminal. Serve para ver se um site responde, conferir cabeçalhos e chamar APIs.

Como ver só o código de resposta de um site?

Use curl -s -o /dev/null -w "%{http_code}" https://exemplo.com. A variável http_code traz o código numérico da última transferência.

Qual a diferença entre -I e -i?

O -I busca só os cabeçalhos, com o comando HEAD. O -i inclui os cabeçalhos da resposta na saída, junto com o corpo.

O que quer dizer o código de saída 6 do curl?

"Could not resolve host": o servidor remoto informado não pôde ser resolvido. Confira o nome e o DNS.

Posso usar -k para ignorar o erro de certificado?

Evite. A documentação diz que a opção torna a transferência insegura. Descubra por que o certificado não valida.