A CLI do VulnCheck

vulncheck é o acesso à API do VulnCheck na linha de comando. Ele traz a navegação de índices, o gerenciamento de backups e a verificação 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 a instalação em todo o sistema (requer sudo) ou a instalação local do usuário.

[!NOTE] O script de instalação também oferece suporte a 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 o preenchimento automático com tab, carregue o script incluído a partir do seu perfil do PowerShell:

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

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

Verificar a instalação

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

vulncheck version

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

Configuração

• Execute vulncheck auth login para autenticar com a sua conta VulnCheck.
• Como alternativa, 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 continua a funcionar e tem precedência quando ambos estão definidos.
• O vulncheck auth por si só mostrará outras opções, como verificar o seu estado e terminar sessão.

Qualquer uma das variáveis de ambiente prevalece sobre o ficheiro de configuração guardado. Por esse motivo, auth login e auth logout recusam enquanto uma delas estiver definida — caso contrário, reportariam sucesso sem terem alterado nada que produza efeito. Execute vulncheck auth status para ver de que origem, e de que variável, veio o token ativo.

Utilização agêntica / em scripts

A CLI foi concebida para ser segura de operar a partir de scripts e agentes de IA. Esta secção é o contrato — as superfícies abaixo destinam-se a permanecer estáveis entre versões (adições não são alterações disruptivas; renomeações/remoções são).

Flags globais

Flag	Efeito
--json	Emite JSON no stdout; encaminha linhas de informação/progresso para stderr; erros emitidos como um envelope estruturado.
--quiet	Suprime a saída informativa. Erros e payloads continuam a ser apresentados.
--no-color	Desativa a estilização ANSI. Também respeita a variável de ambiente NO_COLOR.
--no-interactive	Recusa bloquear em prompts TUI; os comandos que necessitam de um prompt devolvem um erro em vez disso. Implícito por --json, stdin/stdout não-TTY e qualquer 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 — partilhado com os SDKs do VulnCheck e o servidor MCP. Tem precedência sobre ~/.config/vulncheck/vulncheck.yaml; enquanto estiver definida, auth login e auth logout recusam em vez de escrever um ficheiro 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 altere a credencial. Limpe ambas para recorrer ao ficheiro de configuração. auth status indica qual está em uso.
NO_COLOR	Qualquer valor não vazio desativa a estilização ANSI.
CI / BUILD_NUMBER / RUN_ID	Qualquer uma destas definida implica o 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 (argumentos inválidos, flag obrigatória em falta, pedido malformado).
3	Falha de autenticação (sem token, ou o servidor rejeitou o token).
4	Recurso não encontrado (HTTP 404, índice inexistente).
5	Limitado por taxa (HTTP 429).
6	Falha de rede (DNS, ligação recusada, timeout).
130	Cancelado por SIGINT (128 + 2 em POSIX).

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 de: internal, validation, auth_required, auth_invalid, not_found, rate_limited, network, bad_request, cancelled. http_status é omitido para erros não-HTTP. hint é 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": "..."}