A CLI do VulnCheck

vulncheck é o acesso à API do VulnCheck na linha de comando. Ele traz navegação de índices, gerenciamento de backups e varredura de vulnerabilidades para o terminal.

Instalação

Scripts de instalação fornecidos

Você pode instalar facilmente o vulncheck usando um script de instalação. Escolha o script e o método que correspondem ao seu sistema operacional:

macOS e Linux

Abra um terminal e execute:

curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash

Isso solicitará que você escolha entre instalação em todo o sistema (requer sudo) ou instalação local do usuário.

[!NOTE] O script de instalação também suporta opções de instalação não interativa:

• --sudo para instalação em todo o sistema sem prompts
• --non-sudo para instalação local do usuário sem prompts
• --help ou -h para ver todas as opções disponíveis

curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash -s -- --help

Windows

Abra o PowerShell e execute:

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.ps1'))

Para habilitar a conclusão de tabulação, faça dot-source do script incluído no seu perfil do PowerShell:

Add-Content -Path $PROFILE -Value ". '$env:LOCALAPPDATA\Programs\vulncheck\share\powershell\vulncheck.ps1'"

Os binários do vulncheck também estão disponíveis para MacOS, Linux e Windows. Você pode baixar binários pré-compilados na nossa página de releases

Verifique a instalação

Após a instalação, confirme que o binário imprime a versão desejada:

vulncheck version

Você deve ver a versão, a data de build e a URL do changelog. Se você receber "command not found", reabra seu shell para que o novo PATH seja reconhecido e tente novamente.

Configuração

• Execute vulncheck auth login para autenticar com sua conta VulnCheck.
• Alternativamente, o vulncheck respeitará a variável de ambiente VULNCHECK_API_TOKEN — o mesmo nome usado pelos SDKs do VulnCheck e pelo servidor MCP. O legado VC_TOKEN também ainda funciona e tem precedência quando ambos estão definidos.
• vulncheck auth por si só mostrará outras opções, como verificar seu status e fazer logout.

Qualquer uma das variáveis de ambiente tem prioridade sobre o arquivo de configuração salvo. Por causa disso, auth login e auth logout se recusam a executar enquanto uma delas estiver definida — caso contrário, relatariam sucesso sem ter alterado nada que tenha efeito. Execute vulncheck auth status para ver de qual fonte, e de qual variável, veio o token ativo.

Uso agêntico / por script

A CLI foi projetada para ser segura de ser controlada por scripts e agentes de IA. Esta seção é o contrato — as superfícies abaixo devem permanecer estáveis entre releases (adições não são mudanças incompatíveis; renomeações / remoções são).

Flags globais

Flag	Efeito
--json	Emite JSON em stdout; direciona linhas de info/progresso para stderr; erros emitidos como um envelope estruturado.
--quiet	Suprime saída informativa. Erros e payloads ainda são renderizados.
--no-color	Desabilita estilização ANSI. Também respeita a variável de ambiente NO_COLOR.
--no-interactive	Recusa bloquear em prompts de TUI; comandos que precisam de um prompt retornam um erro. Implícito por --json, stdin/stdout não-TTY e qualquer uma das variáveis de ambiente CI / BUILD_NUMBER / RUN_ID.

Variáveis de ambiente

Variável	Efeito
VULNCHECK_API_TOKEN	Token de API, e o nome recomendado — compartilhado com os SDKs do VulnCheck e o servidor MCP. Tem precedência sobre ~/.config/vulncheck/vulncheck.yaml; enquanto definida, auth login e auth logout se recusam a executar em vez de gravar um arquivo que seria ignorado.
VC_TOKEN	Alias legado, ainda totalmente suportado e com precedência sobre VULNCHECK_API_TOKEN quando ambos estão definidos, para que nenhuma configuração existente mude de credencial. Limpe ambos para recorrer ao arquivo de configuração. auth status informa qual está em uso.
NO_COLOR	Qualquer valor não vazio desabilita a estilização ANSI.
CI / BUILD_NUMBER / RUN_ID	Qualquer uma delas definida implica modo não interativo (sem prompts).

Códigos de saída

Código	Significado
0	Sucesso.
1	Erro genérico / interno.
2	Falha de validação (args inválidos, flag obrigatória ausente, requisição malformada).
3	Falha de autenticação (sem token, ou o servidor rejeitou o token).
4	Recurso não encontrado (HTTP 404, índice inexistente).
5	Limite de requisições atingido (HTTP 429).
6	Falha de rede (DNS, conexão recusada, timeout).
130	Cancelado por SIGINT (POSIX 128 + 2).

Envelope de erro

No modo --json, os erros são emitidos para stdout como:

{
  "schema_version": 1,
  "error": {
    "code": "auth_required",
    "message": "...",
    "http_status": 401,
    "hint": "..."
  }
}

code é um dos seguintes: internal, validation, auth_required, auth_invalid, not_found, rate_limited, network, bad_request, cancelled. http_status é omitido para erros não-HTTP. hint é um contexto opcional de remediação, presente apenas quando a mensagem sozinha não é acionável (por exemplo, nomeando a variável que forneceu um token rejeitado). Renderizado em stderr como hint: ... fora do modo --json.

Comandos de sondagem

Use estes para inspecionar a própria CLI antes de despachar trabalho:

vulncheck version --json
# {"schema_version": 1, "version": "...", "build_date": "...", "changelog_url": "..."}