La CLI de VulnCheck

vulncheck es el acceso a la API de VulnCheck desde la línea de comandos. Lleva la navegación de índices, la gestión de copias de seguridad y el escaneo de vulnerabilidades a la terminal.

Instalación

Scripts de instalación proporcionados

Puedes instalar vulncheck fácilmente usando un script de instalación. Elige el script y el método que coincida con tu sistema operativo:

macOS y Linux

Abre una terminal y ejecuta:

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

Esto te pedirá que elijas entre una instalación para todo el sistema (requiere sudo) o una instalación local para el usuario.

[!NOTE] El script de instalación también admite opciones de instalación no interactivas:

• --sudo para una instalación en todo el sistema sin solicitar confirmación
• --non-sudo para una instalación local para el usuario sin solicitar confirmación
• --help o -h para ver todas las opciones disponibles

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

Windows

Abre PowerShell y ejecuta:

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

Para habilitar el autocompletado con tabulador, carga con dot-sourcing el script incluido desde tu perfil de PowerShell:

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

Los binarios de vulncheck también están disponibles para MacOS, Linux y Windows. Puedes descargar binarios precompilados desde nuestra página de releases

Verificar la instalación

Una vez instalado, confirma que el binario muestra la versión deseada:

vulncheck version

Deberías ver la versión, la fecha de compilación y la URL del changelog. Si obtienes "command not found", vuelve a abrir tu shell para que se recoja el nuevo PATH y vuelve a intentarlo.

Configuración

• Ejecuta vulncheck auth login para autenticarte con tu cuenta de VulnCheck.
• Alternativamente, vulncheck respetará la variable de entorno VULNCHECK_API_TOKEN — el mismo nombre que usan los SDK de VulnCheck y el servidor MCP. El legado VC_TOKEN también sigue funcionando, y tiene prioridad cuando ambos están definidos.
• vulncheck auth por sí solo mostrará otras opciones, como comprobar tu estado y cerrar sesión.

Cualquiera de las dos variables de entorno prevalece sobre el archivo de configuración guardado. Por eso, auth login y auth logout se niegan a ejecutarse mientras una esté definida — de lo contrario, informarían de éxito sin haber cambiado nada que surta efecto. Ejecuta vulncheck auth status para ver de qué fuente, y de qué variable, proviene el token activo.

Uso agéntico / con scripts

La CLI está diseñada para ser segura de manejar desde scripts y agentes de IA. Esta sección es el contrato — las superficies a continuación están pensadas para mantenerse estables entre versiones (las adiciones no son cambios incompatibles; los renombrados / eliminaciones sí lo son).

Flags globales

Flag	Efecto
--json	Emite JSON en stdout; redirige las líneas de información/progreso a stderr; los errores se emiten como un sobre estructurado.
--quiet	Suprime la salida informativa. Los errores y las cargas útiles se siguen mostrando.
--no-color	Desactiva el estilo ANSI. También respeta la variable de entorno NO_COLOR.
--no-interactive	Se niega a bloquearse en prompts de TUI; los comandos que necesitan un prompt devuelven un error en su lugar. Implícito por --json, stdin/stdout no TTY, y cualquiera de las variables de entorno CI / BUILD_NUMBER / RUN_ID.

Variables de entorno

Variable	Efecto
VULNCHECK_API_TOKEN	Token de API, y el nombre recomendado — compartido con los SDK de VulnCheck y el servidor MCP. Tiene prioridad sobre ~/.config/vulncheck/vulncheck.yaml; mientras esté definida, auth login y auth logout se niegan a ejecutarse en lugar de escribir un archivo que sería ignorado.
VC_TOKEN	Alias heredado, aún totalmente compatible y con prioridad sobre VULNCHECK_API_TOKEN cuando ambos están definidos, de modo que ninguna configuración existente cambia de credencial. Borra ambas para recurrir al archivo de configuración. auth status informa cuál está en uso.
NO_COLOR	Cualquier valor no vacío desactiva el estilo ANSI.
CI / BUILD_NUMBER / RUN_ID	Cualquiera de estas definida implica modo no interactivo (sin prompts).

Códigos de salida

Código	Significado
0	Éxito.
1	Error genérico / interno.
2	Fallo de validación (argumentos incorrectos, flag requerido ausente, solicitud malformada).
3	Fallo de autenticación (sin token, o el servidor rechazó el token).
4	Recurso no encontrado (HTTP 404, índice inexistente).
5	Limitado por tasa (HTTP 429).
6	Fallo de red (DNS, conexión rechazada, tiempo de espera agotado).
130	Cancelado por SIGINT (POSIX 128 + 2).

Sobre de error

En modo --json, los errores se emiten a stdout como:

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

code es uno de: internal, validation, auth_required, auth_invalid, not_found, rate_limited, network, bad_request, cancelled. http_status se omite para errores que no son HTTP. hint es un contexto de remediación opcional, presente solo cuando el mensaje por sí solo no es accionable (por ejemplo, nombrando la variable que proporcionó un token rechazado). Se muestra en stderr como hint: ... fuera del modo --json.

Comandos de sondeo

Úsalos para inspeccionar la propia CLI antes de despachar trabajo:

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