Session health check: verifies API key resolution (and where the key came from), API connectivity (whoami), the currently active machine, and the VPN assignment in one call. Run this first in any session; exits with an error only when the key or API check fails. Needs HTB_API_KEY (env var or toolkit/.env.local).

List Hack The Box machines. Default is the playable list (page 1); use filter for retired, todo, or unreleased lists, and spTier for Seasonal/starting-point tier lists. Returns compact JSON rows (id, name, os, difficulty, points, active, spawned, free). Lists are cached for 1h; noCache bypasses the cache.

Client-side search over the HTB machine lists, ranked by relevance. Matches id, name, OS, difficulty, tags, makers, points, IP. Use all to also scan retired machines. profiles additionally fetches every scanned machine's profile to match description text — powerful but SLOW (one API request per machine, can take minutes), use it only when list fields are not enough. Follow up with htb_machine_profile on a candidate.

Show a machine profile by id or name (e.g. 444 or 'BoardLight'). Returns an info block: id, name, os, difficulty, points, stars, retired, free, release, maker, user/system owns, tags. Set full=true for the complete raw API payload.

Show the currently active machine: id, name, ip, os, difficulty, expires_at/expires_in, lab server. Always live, never cached. An empty info block means nothing is running. details=true adds the synopsis and linked academy modules.

Start (spawn) a machine by id or name. mode 'auto' (default) tries play then falls back to spawn. With wait=true (default) the CLI retries while spawn capacity is full, then waits for the IP — this can take several minutes at peak times; the response contains {id, name, ip, spawn}. Only one machine can be active at a time: a conflict error names the blocker, stop it (with the user's consent) and retry.

Stop (terminate) a machine; defaults to the currently active machine when target is omitted. This kills the running box and its state — confirm with the user before calling.

Reset a machine to a fresh state; defaults to the currently active machine when target is omitted. Wipes the box back to its initial state — confirm with the user before calling.

Extend a machine's expiry time; defaults to the currently active machine when target is omitted. Non-destructive: the running box and its state are untouched.

Submit a user or root flag for a machine (HTB infers which from the flag value). difficulty is a required rating in steps of 10 from 10 (piece of cake) to 100 (brainfuck) — ask the user if they did not provide one. Submissions are irreversible: confirm with the user first.

List Hack The Box challenges (active by default; retired=true for retired ones). Returns compact JSON rows (id, name, category, difficulty, points, retired, state, solved, solves). Cached for 1h; noCache bypasses the cache.

Client-side search over the (cached) challenge lists, ranked by relevance. Matches id, name, category, difficulty, points, state. Use all to also scan retired challenges. Follow up with htb_challenge_info on a candidate.

Show a challenge by id or name (names resolve case-insensitively). Returns an info block: id, name, category, difficulty, points, stars, retired, state, solved, release, description, solves, maker. Set full=true for the raw API payload.

Submit a challenge flag. difficulty is a required rating in steps of 10 from 10 to 100 — ask the user if they did not provide one. Submissions are irreversible: confirm with the user first.

List the VPN servers the account can use, live (includes VIP/VIP+/dedicated pools), assigned server first. Rows: id, name, group, location, clients, full, assigned. Default product pool is 'labs'. static=true shows only the built-in offline alias table and needs NO API key.

Show the VPN server currently assigned to the account: id, name, location, product — or assigned=false when none.

Switch the account to a different VPN server. Accepts a numeric id (289), a static alias (us-free-1, eu-sp-1, ...) or a live name from htb_vpn_servers (e.g. 'EU Machines VIP+ 1'). Affects the user's whole HTB connection — mention it before switching.

Download an OVPN config file for a server (id, alias, or live name). Default output is lab-vpn.ovpn in the toolkit directory; variant 0 = UDP. The toolkit does NOT run OpenVPN — the user connects themselves with the downloaded file.

Show the user's HTB profile: id, name, rank, points, ranking, user/system owns, respects, country, team, vip. Set full=true for the raw profile payload.

Show rank progression: current rank and points, next rank and its points requirement, current_rank_progress / rank_requirement (percent), rank_ownership, and own counts. Use this to answer 'how close am I to ranking up?'.

Show recent owns (machine user/root flags and challenges), newest first. Rows: date, type (user/root/challenge), id, name, points, blood.

Escape hatch: call any HTB API endpoint directly. Hits the v4 base (https://labs.hackthebox.com/api/v4) by default — pass baseUrl 'https://labs.hackthebox.com/api/v5' for v5 endpoints. path like '/machine/active' (leading slash optional); data takes a raw JSON string body. Set output to save a binary response (for example, GET /challenge/download/) instead of decoding it as text. Relative output paths resolve under the toolkit directory. Use when a typed tool is missing or an endpoint moved.