La CLI de VulnCheck

vulncheck es el acceso a la API de VulnCheck desde la línea de comandos. Trae 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 instalación en todo el sistema sin preguntas
• --non-sudo para instalación local del usuario sin preguntas
• --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, haz dot-source del 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 imprime 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 usado por los SDKs de VulnCheck y el servidor MCP. El legado VC_TOKEN también sigue funcionando, y tiene precedencia cuando ambos están definidos.
• vulncheck auth por sí solo mostrará otras opciones como comprobar tu estado y cerrar sesión.

Cualquiera de las variables de entorno tiene prioridad 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 reportarían é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 permanecer estables entre versiones (las adiciones no son cambios disruptivos; 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 aún se muestran.
--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 SDKs de VulnCheck y el servidor MCP. Tiene precedencia sobre ~/.config/vulncheck/vulncheck.yaml; mientras esté definida, auth login y auth logout se niegan en lugar de escribir un archivo que sería ignorado.
VC_TOKEN	Alias legado, aún totalmente soportado y con precedencia sobre VULNCHECK_API_TOKEN cuando ambos están definidos, para que ninguna configuración existente cambie de credencial. Limpia 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 faltante, 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, timeout).
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 contexto de remediación opcional, presente solo cuando el mensaje por sí solo no es accionable (p. ej., nombrar la variable que proporcionó un token rechazado). Se muestra en stderr como hint: ... fuera del modo --json.

Comandos de sondeo

Usa estos para inspeccionar la CLI misma antes de despachar trabajo:

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