CLI¶
El repositorio Hodeitek/hodeishield-cli
(licencia Apache-2.0) publica hodeishield, el cliente de línea de comandos oficial de
HodeiShield. La última versión tiene
binarios para Linux, macOS y Windows.
0.x
La CLI está en la versión 0.x: los comandos y la salida pueden cambiar todavía antes de la 1.0. La versión vigente para ti está siempre en la página de versiones. El acceso de cartera para un MSSP (ver Varios inquilinos (MSSP)) requiere la 0.4.0 o posterior.
Limitación conocida: macOS y Windows pueden bloquear el binario
El binario de macOS aún no está firmado con un Apple Developer ID ni notarizado, así que Gatekeeper puede negarse a abrir una copia descargada con un navegador; el README del repositorio explica qué hacer en If macOS or Windows blocks the binary, y la incidencia de la CLI hodeishield-cli#16 sigue abierta. Verifica antes la firma (ver más abajo): es la prueba de que el fichero es genuino.
En macOS, tras el primer intento bloqueado, abre Ajustes del Sistema › Privacidad y
seguridad, baja hasta el mensaje sobre hodeishield, pulsa Abrir igualmente, confirma y
vuelve a ejecutar el comando. El texto del diálogo y de los botones sigue el idioma de macOS,
así que puede diferir del que se cita aquí. La alternativa, sólo una vez verificada la firma o
la suma de comprobación, es quitar el atributo de cuarentena del binario desempaquetado:
xattr -d com.apple.quarantine ./hodeishield ("No such xattr" significa que no había nada
que quitar). Una descarga con el navegador pone ese atributo y desempaquetar el archivo con
tar en Terminal lo conserva en el binario, así que el bloqueo sigue aplicándose; una
descarga con curl no lo pone.
Periodo de soporte
Cada versión MAYOR de la CLI tiene 5 años de soporte, contados desde la 1.0.0. La serie 0.x es anterior a la 1.0: las correcciones de seguridad se entregan en la última versión 0.x. El fin del soporte se anuncia con 12 meses de antelación. Las actualizaciones de seguridad siguen disponibles cuando una suscripción caduca; las funciones nuevas requieren una suscripción activa.
Plan
El acceso forma parte de tu licencia de HodeiShield. El servidor MCP requiere el plan Operate o Enterprise. Mientras tu organización está en la beta de HodeiShield, la CLI y el servidor MCP están incluidos con el acceso completo de la beta.
Lee tu inventario de terceros, alertas de cadena de suministro, registro de riesgos,
postura de cumplimiento, evidencias y agentes de endpoint — la misma
API pública /v1 que consume el servidor MCP.
- Sólo lectura. Cada comando es un
GETcontra/v1. Nada de esto puede cambiar datos en tu organización. - Un inquilino, o todos tus clientes. Una clave o una sesión cubre un inquilino; un MSSP lee a sus clientes con una clave de cartera, ver Varios inquilinos (MSSP).
- Segura con las credenciales. Los tokens de sesión viven por defecto en el llavero del sistema; un fichero de tokens en texto plano existe sólo si lo activas expresamente en una máquina sin llavero; nada se imprime ni se registra jamás; las credenciales sólo viajan por HTTPS y nunca se reenvían a una redirección.
- Pensada para scripts.
--jsonimprime el JSON tal cual lo devuelve la API, los códigos de salida dicen qué falló, yHODEISHIELD_API_KEYfunciona sin ningún paso interactivo. - Verificable. Cada versión se firma con Sigstore (sin clave, desde GitHub Actions) y lleva procedencia SLSA.
Instalar y verificar¶
Los métodos de instalación cambian de una versión a otra, así que no se repiten aquí: sigue las
secciones Install y Verify a download del
README del repositorio y descarga desde la
última versión. Cada versión lleva
una firma Sigstore, procedencia SLSA y una lista de materiales de software (SBOM) por artefacto, y
el README muestra los comandos exactos para comprobarlos con la versión que hayas descargado.
Comprueba la firma antes de poner hodeishield en tu PATH.
El README ofrece estas formas de instalarla:
- Un archivo por plataforma: Linux x86_64 y arm64, macOS universal, Windows x86_64 y, desde la 0.4.0, Windows arm64.
- Homebrew (macOS y Linux):
brew install hodeitek/hodeishield/hodeishield. Usa el nombre completo: añade el tap y confía sólo en esa fórmula. - Scoop (Windows):
scoop bucket add hodeishield https://github.com/Hodeitek/scoop-hodeishieldy despuésscoop install hodeishield. - Repositorios APT y DNF firmados en
packages.hodeishield.com(Debian, Ubuntu, Fedora, RHEL y compatibles; x86_64 y arm64), desde la 0.6.0. Ver Instalar con APT o DNF. - Paquetes
.deby.rpm(Linux, x86_64 y arm64), desde la 0.3.0. - El instalador de Windows (
.msi). - Una imagen de contenedor:
ghcr.io/hodeitek/hodeishield-cli. install.sh, firmado, para Linux y macOS, desde la 0.3.0.
Instalar con APT o DNF¶
Los repositorios de packages.hodeishield.com están firmados y las actualizaciones normales de
tu sistema mantienen la CLI al día. Añade el repositorio de tu distribución (apt en Debian y
Ubuntu, dnf en Fedora, RHEL, Rocky Linux y AlmaLinux) y ejecuta sudo apt install hodeishield
o sudo dnf install hodeishield.
Antes de confiar en la clave del repositorio, comprueba su huella. Los comandos exactos, con la descarga de la clave, la comprobación de la huella y la definición del repositorio para cada gestor de paquetes, están en el README de la CLI; síguelos tal cual en lugar de montar los tuyos. La huella se publica sólo allí.
Autenticarse¶
Con una clave de API de inquilino (scripts, CI, servidores)¶
Crea una clave en la app en Configuración › Integraciones y desarrollo › Integraciones › API Key, con sólo los ámbitos de lectura que necesites, y expórtala:
Cuando HODEISHIELD_API_KEY está definida se usa en cada llamada, sea lo que sea lo demás
que esté configurado. Guárdala en el almacén de secretos de tu CI; la CLI nunca la imprime.
hodeishield whoami pregunta a la API quién es la credencial y muestra el inquilino que lee
(nombre e id), su organización y, para una clave, sus ámbitos; para una clave de cartera, el MSSP
y cuántos inquilinos cliente puede seleccionar. Con --json son los campos tenant,
organization, portfolio y credential_scopes.
Iniciando sesión (personas)¶
hodeishield login # abre el navegador; la app redirige de vuelta a 127.0.0.1
hodeishield login --device # sin navegador aqui: aprueba un codigo corto desde otro dispositivo
hodeishield whoami
hodeishield logout # revoca el token en la app y lo borra del llavero
Inicias sesión en app.hodeishield.com como de costumbre (2FA,
passkey o SSO), y en la pantalla de consentimiento eliges el único inquilino que la CLI
puede leer. Un token de sesión nunca cubre más de ese inquilino, y sólo lee. Para usar un
inquilino no relacionado, inicia sesión de nuevo con otro perfil (--profile). Un MSSP no necesita
un perfil por cliente: usa una clave de cartera, ver Varios inquilinos (MSSP).
Con --device, abre la dirección que imprime la CLI en cualquier dispositivo y teclea el
código a mano: la app no acepta un enlace con el código ya relleno, a propósito.
El token se guarda en el llavero del sistema operativo (Llavero de macOS, Administrador de credenciales de Windows, o el Secret Service — GNOME Keyring, KWallet — en Linux) y se renueva automáticamente, también cuando la app termina un token de acceso antes de tiempo. Sin llavero, iniciar sesión se rechaza en vez de recurrir a un fichero: usa una clave de API ahí, que también es lo adecuado para la automatización desatendida.
En un servidor o contenedor que controlas y donde quieres iniciar sesión como tú, puedes activar
un fichero de tokens en texto plano con HODEISHIELD_TOKEN_STORE=plaintext-file (o
hodeishield config set token_store plaintext-file). Por defecto sigue siendo keychain. Los
tokens se guardan entonces sin cifrar en un fichero que sólo tu usuario puede leer, así que
cualquiera que pueda leer tus ficheros puede usarlos; es una elección expresa, nunca un
respaldo, y todavía no está disponible en Windows.
Para cortar el acceso de la CLI desde otro sitio, revócalo en la app en Cuenta → Accesos de aplicaciones.
Usar¶
hodeishield vendors list --criticality critical
hodeishield vendors get 0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e
hodeishield alerts list --status open --since 2026-01-01T00:00:00Z
hodeishield risks list --min-inherent-score 15 --sort inherent_score
hodeishield compliance posture nis2
hodeishield compliance controls --framework nis2 --status failing
hodeishield evidence list --expiring-before 2026-12-31T00:00:00Z
hodeishield endpoints list --status active
Los listados muestran una página (50 elementos por defecto); --page, --per-page (hasta
200) y --all recorren el resto. Todo listado acepta --sort y --order; --help en
cualquier comando enumera lo que acepta.
Informes¶
reports list y reports get muestran los informes generados para el inquilino; reports
download guarda el fichero de un informe completado. Necesitan el ámbito reports:read.
hodeishield reports list --status completed
hodeishield reports get 7d3e1f2a-4b5c-4d6e-8f70-81a2b3c4d5e6 # incluye los formatos en que puede descargarse
hodeishield reports download 7d3e1f2a-4b5c-4d6e-8f70-81a2b3c4d5e6 --format xlsx --locale es
reports list filtra por --type, --status y --since. --format es pdf (por defecto) o
xlsx; --locale es uno de es, en (por defecto), de, fr, it y eu. El fichero se
guarda en el directorio actual o en --output <RUTA>; un fichero existente sólo se sustituye
con --force. Un informe que aún se está generando, que falló o que no tiene fichero en ese
formato se rechaza con un mensaje que lo dice.
JSON para scripts¶
--json imprime el cuerpo que devolvió la API, sin tocarlo, incluidos campos más nuevos que
tu CLI. Con --all, imprime un único array JSON con todos los elementos:
CSV para hojas de cálculo¶
--csv imprime los elementos de cualquier comando list (y de compliance controls) como CSV
en lugar de tabla; funciona con --all y no con --json:
Las lecturas se reintentan automáticamente (hasta dos veces, con espera creciente) cuando la API responde 502, 503 o 504, o falla la conexión.
Códigos de salida¶
| Código | Significado |
|---|---|
| 0 | Éxito |
| 1 | Error (entrada inválida, configuración, respuesta inesperada) |
| 2 | Línea de comandos inválida |
| 3 | No autenticado: sin credencial (también cuando el llavero del sistema no es accesible en esta sesión), o la API la rechazó |
| 4 | La credencial no tiene el ámbito que el comando necesita |
| 5 | No encontrado (o no está en tu organización) |
| 6 | Límite de tasa agotado (la CLI ya reintentó esperas cortas) |
| 7 | La API no se pudo alcanzar o falló, o aún no ofrece acceso de cartera |
| 8 | La licencia del inquilino no está vigente: un administrador del inquilino debe renovarla o reactivarla |
Los errores van a stderr con una pista y, cuando la API dio uno, un id de petición:
cítalo si contactas con soporte. --verbose registra en stderr el método, la URL, el
estado y el id de petición de cada llamada, nunca una credencial.
Varios inquilinos (MSSP)¶
Un MSSP lee todos sus inquilinos cliente con una sola credencial, una clave de cartera (portfolio key), en lugar de una clave o un perfil por cliente.
Cómo se acota la clave
- La crea en la app un administrador de organización de una organización MSSP activa, en el área de MSSP (claves de API). Nadie más puede crearla: ni un administrador de inquilino, ni un operador de plataforma que actúe fuera de una organización MSSP.
- Empieza por
hsp_, es de sólo lectura salvo que un administrador de la organización le haya concedidoalerts:write(que permite reconocer y resolver alertas a través de/v1, ver Autenticación; la propia CLI sigue siendo de sólo lectura), caduca siempre (90 días por defecto, 365 como máximo) y funciona únicamente en la API de HodeiShield. - Al crearla se puede limitar a algunos de tus clientes y a rangos de IP de origen. Una petición desde otra dirección se rechaza como una clave desconocida (código de salida 3).
- Iniciar sesión con
hodeishield loginno cubre toda una cartera: usa la clave. - Rótala antes de que caduque: una clave nueva y su predecesora funcionan a la vez hasta 7 días mientras la antigua siga vigente. Revócala en la misma área de MSSP; deja de funcionar en su siguiente petición.
Úsala como cualquier otra clave
export HODEISHIELD_API_KEY=hsp_... # la clave de cartera; guárdala en el almacén de secretos de tu CI
hodeishield tenants list
$ hodeishield tenants list
SLUG NAME ORGANISATION TYPE STATUS LICENCE ID
acme Acme S.L. Acme Group client active in_force 11111111-1111-4111-8111-111111111111
beta Beta Corp Beta Group client active grace 22222222-2222-4222-8222-222222222222
tenants list muestra los inquilinos que la clave puede leer: los de tu propia organización
(TYPE own) y tus clientes, también los inactivos o sin licencia vigente, que las columnas
STATUS y LICENCE distinguen. Admite --json, --csv, --page y --all. La lista se lee de la
API cada vez, así que un cliente añadido o quitado de tu cartera aparece en el siguiente comando.
Elegir el cliente
La elección acompaña a cada comando y nunca se recuerda, de modo que un comando posterior no puede leer otro cliente por sorpresa.
hodeishield --tenant acme vendors list # un cliente, por slug o id
hodeishield --all-tenants alerts list --status open
hodeishield --all-tenants vendors list --criticality critical --csv > critical-vendors.csv
--tenant <slug|id>funciona en todos los comandos de lectura (list,get,compliance posture). La CLI imprimeClient tenant: acme (<id>)por la salida de error, de modo que un registro muestra qué cliente se leyó.--all-tenantsfunciona en los comandoslisty encompliance controls. Lee cada cliente uno tras otro (--per-pagese aplica,--pageno) y añade el inquilino a cada fila: una columnaTENANTen la tabla ytenant_id,tenant_slugytenant_nameen--jsony--csv.--tenanty--all-tenantsno se pueden combinar.
hodeishield --all-tenants alerts list --status open --json \
| jq -r '.[] | [.tenant_slug, .severity, .title] | @tsv'
Si llamas directamente a la API, el cliente se elige con la cabecera
X-HS-Tenant, que lleva el id del inquilino (un UUID), nunca un slug; consulta la
referencia de la API.
Qué se rechaza
- Sin
--tenantni--all-tenants, la API rechaza una clave de cartera y la CLI te dice que elijas. - Un cliente que no está en tu cartera, o que has escrito mal, falla con código de salida 5 antes de leer nada. Ambos casos tienen la misma respuesta.
- Un cliente indicado que está desactivado, o cuya licencia no está vigente, falla con código de salida 8.
- Una clave de API de inquilino o una sesión iniciada a la que se pide un cliente falla con código de salida 4: no tiene el ámbito de cartera. Sin esas opciones se comportan como antes.
- Con
--all-tenants, un cliente que no se puede leer (inactivo, licencia no vigente, no encontrado, o con un estado de licencia que esta versión de la CLI no conoce) se nombra por la salida de error y se omite. El comando imprime los demás clientes y después sale con un código distinto de cero, de modo que un script nunca toma un resultado parcial por completo: comprueba el código de salida y lee la salida de error para saber qué clientes quedaron fuera. - Un slug que parece el id de otro cliente se rechaza por ambiguo: usa el id que muestra
tenants list. - Los límites de tasa se aplican por clave de cartera (100 peticiones por minuto) y a todas las
claves de cartera de tu organización juntas (600); la API puede cambiar estas cifras, y los
límites propios de un cliente pueden ser menores. Cuando uno se agota, el comando se detiene
con código de salida 6 e indica qué límite alcanzó. Usa
--per-page 200y filtros para necesitar menos peticiones. - Contra una API que aún no ofrece acceso de cartera, estas opciones fallan con código de salida 7.
Configurar¶
Los ajustes vienen, en este orden: flags, variables de entorno, el perfil del fichero de
configuración, y los valores por defecto (https://api.hodeishield.com,
https://app.hodeishield.com).
hodeishield config show # los ajustes en efecto
hodeishield config path # donde esta el fichero
hodeishield --profile staging config set api_url https://api.example.test
hodeishield config use staging # hazlo el perfil por defecto
hodeishield --profile default vendors list # o elige uno por comando
| Variable | Propósito |
|---|---|
HODEISHIELD_API_KEY |
Clave de API de inquilino o clave de cartera de MSSP (hsp_...); tiene prioridad sobre una sesión iniciada |
HODEISHIELD_PROFILE |
Perfil a usar |
HODEISHIELD_API_URL |
URL base de la API |
HODEISHIELD_APP_URL |
URL base de la app (inicio de sesión) |
HODEISHIELD_CONFIG |
Ruta del fichero de configuración |
HODEISHIELD_TOKEN_STORE |
Dónde se guardan los tokens de sesión: keychain (por defecto) o plaintext-file, una activación expresa; tiene prioridad sobre token_store del fichero de configuración |
HODEISHIELD_NO_UPDATE_CHECK |
Cualquier valor no vacío desactiva el aviso de una línea de versión nueva (también hodeishield config set update_check false) |
El fichero de configuración guarda sólo URLs y ajustes de sesión, nunca una credencial (el
fichero de tokens opcional es otro fichero distinto). Las
URL deben usar HTTPS; el HTTP plano sólo se acepta para localhost.
Completado de shell: hodeishield completions bash|zsh|fish|powershell|elvish.
Siguiente paso¶
- Servidor MCP — la misma API, alojada, sin instalación
- Visión general de la API
- Repositorio en GitHub