htb-cli

A terminal client for Hack The Box. Browse machines, challenges, Sherlocks, and seasons. Spawn instances, submit flags, manage VPN connections.

Works with any HTB account (free or VIP).

Install

cargo install htb-cli

Or download a binary from releases.

Setup

# Save your API token (from https://app.hackthebox.com/account-settings)
htb auth login

# Verify it works
htb auth status

Usage

# Machines
htb machines list --os linux --difficulty easy
htb machines info Bedside
htb machines start Bedside
htb machines submit Bedside 'HTB{flag_here}'
htb machines active

# Challenges
htb challenges list --category Web
htb challenges categories
htb challenges info Poly
htb challenges start Poly
htb challenges submit 112 'HTB{flag_here}'
htb challenges download Poly

# Sherlocks
htb sherlocks list --category DFIR
htb sherlocks info Brutus

# Seasons
htb seasons list
htb seasons rank

# VPN
htb vpn status
htb vpn list
htb vpn switch 1
htb vpn download

# User
htb user me
htb user info 1234567

# Search
htb search nmap

# PwnBox
htb pwnbox usage
htb pwnbox status

CTF Events

The CTF platform uses a separate token and API. Authenticate first, then browse events, work challenges, and track scores.

# Authenticate with the CTF platform (separate token from labs)
htb ctf auth login
htb ctf auth status

# Browse events
htb ctf events                                  # ongoing and upcoming
htb ctf events --all                            # include past events
htb ctf info ctf-try-out-1434                   # event details by slug

# Work challenges
htb ctf challenges 1434                         # list challenges in event
htb ctf challenges 1434 --difficulty easy       # filter by difficulty
htb ctf start 1434 31855                        # start a docker container
htb ctf download 1434 31855                     # download challenge files
htb ctf submit 31855 'HTB{flag_here}'           # submit a flag
htb ctf stop 1434 31855                         # stop the container

# Scoreboard and solves
htb ctf scoreboard 1434                         # team rankings
htb ctf solves 1434                             # recent solves feed
htb ctf challenge-solves 31855                  # who solved a challenge

# Clean up
htb ctf auth logout

The CTF token is stored separately at ~/.htb-cli/.ctf-token. Get it from your CTF platform settings after logging in at ctf.hackthebox.com.

Output

Table output by default. Use --json on any command for machine-readable output:

htb machines list --json
htb auth status --json

Pipe through jq to filter, slice, or reshape:

# Easy Linux machines you haven't completed
htb machines list --json | jq '[.[] | select(.os == "Linux" and .difficulty == "Easy" and .user_owned == false)]'

# Names of ongoing CTF events
htb ctf events --json | jq '[.[] | select(.status == "Ongoing")] | .[].name'

# Challenge IDs you haven't solved yet
htb ctf challenges 1434 --json | jq '[.[] | select(.solved == false)] | .[].id'

# Your current rank
htb seasons rank --json | jq '.rank'

MCP Server

Run as an MCP server for AI agent integration:

htb --mcp-stdio

Exposes tools: list_machines, get_machine_info, list_challenges, get_challenge_info, start_challenge, submit_challenge_flag, get_active_machine, list_seasons, search, get_user_profile.

Claude Code config

{
  "mcpServers": {
    "htb": {
      "command": "htb",
      "args": ["--mcp-stdio"]
    }
  }
}

Config

Optional config at ~/.htb-cli/config.toml:

output = "table"   # or "json"
vpn_server = 1     # default VPN server ID
no_color = false

Token stored at ~/.htb-cli/.token (0600 permissions).

License

MIT