htb — Cliente de terminal para HackTheBox

CLI minimalista en Bash para HackTheBox usando la API oficial (v4, con v5 para el envío de flags). Diseñado para ir rápido: spawnea máquinas, coge la IP, manda flags — sin salir de la terminal.

htb spawn Connected      →  spawnea la máquina, espera la IP y la copia al portapapeles
htb own <hash>           →  sube la flag a la máquina activa automáticamente
htb season               →  lista las máquinas de la season con estado de bloods

Características

Solo necesita curl y jq — sin Python, sin npm, sin dependencias raras
Resuelve nombres de máquinas a IDs automáticamente (busca en season → lista general → búsqueda libre)
Después del spawn, espera la IP y la copia al portapapeles (xclip)
Detecta la máquina activa automáticamente en own, stop, reset e ip
Interfaz con iconos y colores autodetectados: usa glifos Nerd Font si los tienes, emoji si no, y ASCII puro cuando la salida va a un fichero o TERM no es UTF-8
Iconos por sistema operativo (Windows/Linux/BSD/macOS), dificultad coloreada y marcas de own / blood
htb font instala una Nerd Font sin tocar el gestor de paquetes (igual en Arch, Debian, Fedora o macOS)
El token se guarda una vez en ~/.config/htb/token o se pasa por variable de entorno
Gestión de VPN integrada: varios perfiles (Labs, Fortress, Starting Point…), descarga por producto, conexión con selector y cambio en caliente

Requisitos

Herramienta	Para qué
`bash` ≥ 4	Shell
`curl`	Llamadas a la API
`jq`	Parseo de JSON
`xclip`	Copiar IP al portapapeles tras spawn (opcional)
`fontconfig`	Detectar/instalar Nerd Fonts (opcional)
`unzip`, `bsdtar` o `python3`	Extraer la fuente en `htb font` (cualquiera de los tres)
`openvpn`	VPN con `htb connect` (opcional)

Instalación

# 1. Clonar
git clone https://github.com/C4sh3R/htb-cli.git
cd htb-cli

# 2. Instalar
chmod +x htb
cp htb ~/.local/bin/htb        # o: sudo cp htb /usr/local/bin/htb

# 3. Guardar el token de la API
mkdir -p ~/.config/htb
echo "TU_TOKEN_AQUI" > ~/.config/htb/token
chmod 600 ~/.config/htb/token

El token lo sacas de HackTheBox → Account Settings → API Token.

Alternativa: variable de entorno

export HTB_TOKEN="eyJ0eXAiOiJKV1..."

Carpeta de VPNs

HTB da un .ovpn distinto por producto (Labs, Fortress, Starting Point, Release Arena…). htb los guarda todos juntos en una carpeta y tú eliges cuál conectar.

La carpeta se autodetecta entre ~/Desktop/c4sh3r/HTB/vpn, ~/HTB/vpn y ~/.config/htb/vpn (la primera que exista). Para fijar la tuya:

export HTB_VPN_DIR="/ruta/a/tus/ovpn"

Si prefieres el comportamiento antiguo de un único archivo fijo, HTB_VPN_FILE sigue funcionando y salta el selector:

export HTB_VPN_FILE="/ruta/a/tu/machines.ovpn"

Uso

htb <comando> [argumentos]

Referencia rápida

Comando	Descripción
`htb whoami`	Muestra tu usuario y estado VIP
`htb list [N]`	Últimas N máquinas (por defecto 15), más recientes primero
`htb latest`	La máquina más reciente (la release de hoy)
`htb season`	Máquinas de la season activa con estado de bloods
`htb info <nombre\|id>`	Perfil de una máquina: owns, rank y first bloods
`htb active`	Máquina spawneada ahora mismo + IP
`htb spawn <nombre\|id>`	Spawnea una máquina y espera la IP
`htb ip [nombre\|id]`	Espera e imprime la IP de la máquina activa
`htb stop [nombre\|id]`	Termina la máquina activa (o la que indiques)
`htb reset [nombre\|id]`	Resetea la máquina activa (o la que indiques)
`htb own <flag> [dif]`	Sube una flag a la máquina activa
`htb own <nombre\|id> <flag> [dif]`	Sube una flag a una máquina concreta
`htb vpn [producto]`	Descarga el `.ovpn` de un producto (`labs`, `sp`, `fortress`…)
`htb vpns`	Lista tus perfiles VPN locales y marca el conectado
`htb connect [perfil]`	Conecta la VPN (menú si no dices cuál)
`htb disconnect [perfil]`	Desconecta solo la VPN lanzada por `htb` (por PID)
`htb vpnstatus`	Qué VPN está conectada y con qué perfil
`htb icons`	Muestra el juego de iconos detectado
`htb font [Fuente]`	Instala una Nerd Font (por defecto `Hack`)
`htb version`	Versión de `htb`

Comandos en detalle

`htb whoami`

Comprueba que el token funciona y muestra tu cuenta.

$ htb whoami
Usuario: C4sh3R  (id 12345)
VIP: true  Server: eu-vip-2

`htb list [N]`

Las N máquinas más recientes. Muestra si ya tienes user (U:1) o root (R:1).

$ htb list 5
906  Connected  Linux   Easy    2025-11-30  U:1 R:0
905  VariaType  Linux   Medium  2025-11-23  U:0 R:0
904  Pupilpath  Windows Hard    2025-11-16  U:1 R:1

`htb latest`

La máquina más reciente de todas. Ideal para ver qué ha salido hoy.

$ htb latest
Mas reciente:
  ID:         906
  Nombre:     Connected
  OS:         Linux
  Dificultad: Easy
  Release:    2025-11-30T20:00:00.000000Z
  Activa:     1

`htb season`

Todas las máquinas de la season activa con fecha de release y estado de bloods.

$ htb season
906  Connected  Linux  Easy    rel:2025-11-30  released:true  Ublood:false  Rblood:false
905  VariaType  Linux  Medium  rel:2025-11-23  released:true  Ublood:true   Rblood:false

`htb spawn <nombre|id>`

Spawnea por nombre o por ID numérico. El script resuelve el nombre en este orden:

Lista de máquinas de la season (las nuevas releases están aquí)
Lista paginada general (top 100 recientes)
Endpoint de búsqueda libre de HTB

Tras el spawn, hace polling cada 2 segundos hasta que la IP está asignada, la imprime y la copia al portapapeles.

$ htb spawn Connected
[*] Spawneando maquina id 906 ...
[+] Machine deployed
[*] Esperando IP...
[+] IP: 10.129.9.213
    (copiada al portapapeles)

`htb ip`

Espera hasta 80 segundos a que la máquina activa tenga IP. Útil si spawneaste en otra sesión.

$ htb ip
[+] IP: 10.129.9.213
    (copiada al portapapeles)

`htb active`

Muestra qué máquina tienes spawneada ahora mismo.

$ htb active
Activa: Connected (id 906)
IP: 10.129.9.213
Expira: 2025-12-01 08:00:00

`htb own <flag> [dificultad]`

Sube una flag a la máquina activa. La dificultad es un número del 1 al 10 (por defecto 5).

# Flag a la máquina activa (auto-detectada)
htb own 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

# Con dificultad explícita
htb own 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d 3

# A una máquina específica por nombre
htb own Connected 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

Respuesta si es correcta:

[+] Congratulations! You have got the user flag on Connected.

`htb reset`

Resetea la máquina activa. Muy útil cuando algo se queda pillado durante la explotación.

$ htb reset
[+] The machine has been scheduled for reset.

`htb stop`

Termina la máquina y libera el slot de VPN.

$ htb stop
[+] Machine stopped.

`htb info <nombre|id>`

Perfil completo de una máquina: sistema, dificultad, puntos, IP, tus owns con el tiempo que tardaste, tu posición en la máquina y quién se llevó las first bloods. Si la blood es tuya, aparece marcada.

$ htb info Scaffold
╭──────────────────────────────────────────────────────────────────────╮
│   Scaffold                                                          │
╰──────────────────────────────────────────────────────────────────────╯
   ID            978
   Sistema         Windows
   Dificultad    ● Hard
   Puntos        40
   IP            (no spawneada)
   Release       2026-09-05
   Activa        ● si

   User own        en 1H 2M 14S
   Root own        en 0H 41M 54S
   Tu rank       #16

   User blood     admiin  0H 28M 7S
   Root blood     ahos6  0H 10M 46S

El dueño de cada blood se compara con el ID del usuario autenticado, que se obtiene de /user/info en tiempo de ejecución: no hay ningún ID fijado en el código, así que cada uno ve marcadas sus propias bloods.

`htb vpn [producto]`

Descarga el .ovpn del producto que le digas, usando el servidor que tengas asignado en HTB. Sin argumentos lista los productos y a qué servidor estás asignado en cada uno:

$ htb vpn
╭──────────────────────────────────────────╮
│ Productos VPN de HackTheBox              │
╰──────────────────────────────────────────╯
  labs                EU Machines VIP+ 5        EU
  starting_point      EU StartingPoint 1        EU
  fortresses          EU Fortress 1             EU
  endgames            sin acceso

Con un producto, lo descarga a tu carpeta de VPNs:

$ htb vpn fortress
🚀 Consultando servidores de fortresses ...
🚀 Descargando EU Fortress 1 (id 429) ...
✅ VPN guardada en ~/HTB/vpn/fortresses_eu-fort-1.ovpn  (edge-eu-fort-1.hackthebox.eu)
   Conectar: htb connect fortresses_eu-fort-1

Alias aceptados: labs/machines/vip, sp/starting, fortress, endgame, arena/release, season.

Opción	Qué hace
`-p`, `--pick`	Menú para elegir un servidor concreto en vez del asignado
`--tcp`	Descarga la variante TCP
`-o <ruta>`	Guarda en una ruta concreta

El nombre del archivo se deriva del servidor (eu-fort-1, eu-dedivip-5…). Si ya tenías un .ovpn de ese mismo servidor, actualiza ese archivo en su sitio en vez de crear un duplicado.

`htb vpns`

Lista los .ovpn de tu carpeta, con el tipo de lab que es cada uno y cuál está conectado ahora:

$ htb vpns
╭──────────────────────────────────────────╮
│ Perfiles VPN   ~/HTB/vpn                 │
╰──────────────────────────────────────────╯
  ·  eu-starting-point-1-dhcp   Starting Point  edge-eu-starting-point-1-dhcp.hackthebox.eu
  ●  fortresses_eu-fort-1       Fortress        edge-eu-fort-1.hackthebox.eu   ✅ conectado
  ·  htb                        Labs VIP+       edge-eu-dedivip-5.hackthebox.eu

`htb connect [perfil]`

Conecta la VPN con openvpn --daemon y espera hasta 15 segundos a que tun0 suba. Guarda el PID del proceso en /run/htb-openvpn.pid (HTB_VPN_PID_FILE) para que htb disconnect sepa exactamente cuál es su proceso.

El perfil se puede escribir de varias formas — todas estas valen:

htb connect fortress                  # alias de producto
htb connect fort                      # trozo del nombre
htb connect fortresses_eu-fort-1      # nombre del archivo
htb connect ~/vpn/mi-config.ovpn      # ruta directa

Sin argumento, si tienes más de un .ovpn te saca un menú:

$ htb connect

  Perfiles VPN en ~/HTB/vpn

    1) Starting Point  edge-eu-starting-point-1-dhcp.hackthebox.eu
       eu-starting-point-1-dhcp.ovpn
    2) Fortress        edge-eu-fort-1.hackthebox.eu
       fortresses_eu-fort-1.ovpn
    3) Labs VIP+       edge-eu-dedivip-5.hackthebox.eu
       htb.ovpn

  Elige [1-3]: 2
🚀 Conectando fortresses_eu-fort-1.ovpn (sudo)
✅ VPN arriba (Fortress): 10.10.15.177/23

Solo mantiene una VPN de HTB a la vez. Si ya hay una conectada y pides otra, te avisa y pregunta antes de cambiar (-f para no preguntar):

$ htb connect labs -f
⚠️  Ya hay una VPN de htb activa: fortresses_eu-fort-1.ovpn
📌 Cambiando a htb.ovpn ...
🚀 Desconectando fortresses_eu-fort-1.ovpn (pid 20999, sudo)
✅ VPN desconectada (pid 20999 terminado).
🚀 Conectando htb.ovpn (sudo)
✅ VPN arriba (Labs VIP+): 10.10.14.73/23

Si el perfil que pides no existe, o es ambiguo, te lo dice sin tocar nada:

$ htb connect eu
❌ 'eu' coincide con varios perfiles:
   - eu-starting-point-1-dhcp.ovpn
   - fortresses_eu-fort-1.ovpn

Si guardas tu contraseña de sudo en ~/.config/htb/sudo.pass, la conexión es completamente no interactiva:

echo "tu_password_sudo" > ~/.config/htb/sudo.pass
chmod 600 ~/.config/htb/sudo.pass

`htb disconnect [archivo.ovpn]`

Corta únicamente la VPN que levantó htb: lee el PID de /run/htb-openvpn.pid, comprueba que ese proceso siga vivo y sea realmente un openvpn, y lo mata. Nunca hace pkill openvpn, así que otras sesiones VPN del sistema (trabajo, otro lab, otro .ovpn) siguen intactas. Usa ~/.config/htb/sudo.pass si existe para no pedir contraseña.

$ htb disconnect
[*] Desconectando VPN de htb (pid 4821, sudo)...
[+] VPN desconectada (pid 4821 terminado).

Si no hay pidfile válido (por ejemplo, una VPN levantada con una versión anterior), busca procesos openvpn lanzados con algún .ovpn de tu carpeta de VPNs (o con el perfil que le pases). Si encuentra exactamente uno, lo mata; si hay varios, o si los openvpn en marcha no son suyos, no toca nada y te los lista:

$ htb disconnect
[*] Hay openvpn corriendo, pero ninguno lo lanzo htb.
    No toco VPNs ajenas. Procesos actuales:
3390 openvpn --config /home/user/work.ovpn --daemon

`htb vpnstatus`

Comprueba si tun0 está activo y con qué perfil.

$ htb vpnstatus
🌐  VPN conectada  10.10.15.177/23
   perfil: fortresses_eu-fort-1.ovpn (Fortress)
   openvpn de htb: pid 20999

$ htb vpnstatus
[+] VPN conectada: 10.10.14.5/23
    (openvpn de htb: pid 4821)

Workflow típico — First Blood

# 1. Conectar VPN (una vez por sesión)
htb connect

# 2. Ver qué ha salido
htb latest
htb season

# 3. Spawnear
htb spawn Connected

# 4. ... hackear ...

# 5. Subir flags
htb own <hash_user>
htb own <hash_root>

# 6. Limpiar
htb stop
htb disconnect   # cortar la VPN al terminar

Ejemplos de uso frecuentes

# Ver si tienes la VPN activa
htb vpnstatus

# Spawnear por nombre o por ID
htb spawn 906
htb spawn Connected

# Ver la máquina que tienes ahora mismo
htb active

# Resetear si la máquina se ha quedado pillada
htb reset

# Subir flag con dificultad baja (era fácil)
htb own abc123... 2

# Subir flag a una máquina concreta sin que sea la activa
htb own VariaType def456... 7

# Listar las últimas 30 máquinas
htb list 30

# Buscar info de cualquier máquina
htb info "Lame"
htb info 1

Seguridad del token

El token se lee en este orden:

Variable de entorno $HTB_TOKEN
Fichero ~/.config/htb/token (o $HTB_TOKEN_FILE)

Asegúrate de que el fichero solo lo puede leer tu usuario:

chmod 600 ~/.config/htb/token

Apariencia

htb decide solo cómo pintarse, en este orden:

Modo	Cuándo se elige	Ejemplo
`nerd`	Hay una Nerd Font instalada (`fc-list`)
`emoji`	Terminal UTF-8 sin Nerd Font	`🪟` `🐧`
`ascii`	Sin UTF-8, o la salida va a un fichero/pipe	`WIN` `LNX`

Los anchos de columna se calculan sobre el ancho visible real (ignorando los códigos ANSI y contando los emoji como dos columnas), así que la tabla queda alineada en los tres modos.

htb icons                 # ver qué modo se ha detectado
HTB_ICONS=emoji htb list  # forzar un modo concreto
NO_COLOR=1 htb list       # sin color

`htb font [Fuente]`

Instala una Nerd Font en el directorio de fuentes del usuario y refresca la caché. No usa pacman, apt ni dnf, así que funciona igual en cualquier distro:

htb font              # instala Hack Nerd Font
htb font JetBrainsMono

Descarga desde las releases de ryanoasis/nerd-fonts a ~/.local/share/fonts (o ~/Library/Fonts en macOS), extrae con unzip, bsdtar o python3 —lo que haya— y ejecuta fc-cache. Después hay que seleccionar la fuente en los ajustes de la terminal; el comando imprime la línea de configuración para kitty, alacritty y wezterm.

Variables de configuración

Variable	Por defecto	Descripción
`HTB_TOKEN`	—	Token de la API (override por env)
`HTB_TOKEN_FILE`	`~/.config/htb/token`	Ruta al fichero de token
`HTB_VPN_FILE`	(ruta hardcodeada)	Config VPN por defecto para `htb connect`
`HTB_VPN_PID_FILE`	`/run/htb-openvpn.pid`	PID del `openvpn` lanzado por `htb` (lo usa `htb disconnect`)
`HTB_ICONS`	(autodetección)	Fuerza el juego de iconos: `nerd`, `emoji` o `ascii`
`NO_COLOR`	—	Si está definida, desactiva el color
`HTB_NF_VERSION`	`v3.4.0`	Release de nerd-fonts que descarga `htb font`

Licencia

MIT — úsalo como quieras.

Name		Name	Last commit message	Last commit date
LICENSE		LICENSE
README.md		README.md
htb		htb

Navigation Menu

Repository files navigation

htb — Cliente de terminal para HackTheBox

Características

Requisitos

Instalación

Alternativa: variable de entorno

Carpeta de VPNs

Uso

Referencia rápida

Comandos en detalle

`htb whoami`

`htb list [N]`

`htb latest`

`htb season`

`htb spawn <nombre|id>`

`htb ip`

`htb active`

`htb own <flag> [dificultad]`

`htb reset`

`htb stop`

`htb info <nombre|id>`

`htb vpn [producto]`

`htb vpns`

`htb connect [perfil]`

`htb disconnect [archivo.ovpn]`

`htb vpnstatus`

Workflow típico — First Blood

Ejemplos de uso frecuentes

Seguridad del token

Apariencia

`htb font [Fuente]`

Variables de configuración

Licencia

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

htb — Cliente de terminal para HackTheBox

Características

Requisitos

Instalación

Alternativa: variable de entorno

Carpeta de VPNs

Uso

Referencia rápida

Comandos en detalle

htb whoami

htb list [N]

htb latest

htb season

htb spawn <nombre|id>

htb ip

htb active

htb own <flag> [dificultad]

htb reset

htb stop

htb info <nombre|id>

htb vpn [producto]

htb vpns

htb connect [perfil]

htb disconnect [archivo.ovpn]

htb vpnstatus

Workflow típico — First Blood

Ejemplos de uso frecuentes

Seguridad del token

Apariencia

htb font [Fuente]

Variables de configuración

Licencia

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`htb whoami`

`htb list [N]`

`htb latest`

`htb season`

`htb spawn <nombre|id>`

`htb ip`

`htb active`

`htb own <flag> [dificultad]`

`htb reset`

`htb stop`

`htb info <nombre|id>`

`htb vpn [producto]`

`htb vpns`

`htb connect [perfil]`

`htb disconnect [archivo.ovpn]`

`htb vpnstatus`

`htb font [Fuente]`