htb-cli

README

htb-cli — maintained fork

htb-cli provides terminal access to Hack The Box machines, challenges, Sherlocks, VPN configuration, profile information, submissions, and related workflows.

This repository is a maintained fork of GoToolSharing/htb-cli. It keeps the original history and GPLv3 license while restoring compatibility with the current Hack The Box APIs.

Maintained changes

• Uses the current HTB API v5 endpoint for profile activity.
• Displays machine, challenge, Sherlock, and fortress activity with local time and awarded points.
• Avoids the profile TUI crash caused by the removed v4 activity endpoint.
• Supports non-interactive machine and Sherlock listings without /dev/tty.
• Filters Machines, Challenges, Sherlocks, and Pro Labs by difficulty.
• Provides a complete Challenge workflow: list, inspect, download, extract, submit, and verify ownership without requiring curl.
• Includes the latest changes from the original dev branch.

Installation

Go 1.20 or newer is required.

go install github.com/PsyGuy007-sys/htb-cli@main
htb-cli version

Precompiled releases will use stable version tags when they are published.

Configuration

Create an application token from your Hack The Box account settings. The recommended configuration is a user-only token file:

install -d -m 700 ~/.config/htb-cli
${EDITOR:-vi} ~/.config/htb-cli/token
chmod 600 ~/.config/htb-cli/token

htb-cli checks HTB_TOKEN first and then $XDG_CONFIG_HOME/htb-cli/token (normally ~/.config/htb-cli/token). It refuses a token file accessible by the group or other users.

For a temporary session, the environment variable remains supported:

export HTB_TOKEN="your-application-token"

Keep tokens out of repositories, command history, screenshots, logs, and issue reports.

Usage

htb-cli --help
htb-cli machines
htb-cli challenges
htb-cli info --batch
htb-cli sherlocks
htb-cli vpn
htb-cli submit --machine Cobblestone

List HTB content by difficulty without opening an interactive interface:

htb-cli machines --difficulty Hard --batch
htb-cli challenges --difficulty Hard --state active --batch
htb-cli sherlocks --difficulty "Very Easy" --batch
htb-cli prolabs --difficulty Advanced --batch

Complete Challenge workflow

The Challenge commands talk directly to the authenticated HTB API. They do not require a separate curl command.

1. Find a challenge

# Active Easy challenges that are not yet owned are visible in the OWNED column.
htb-cli challenges --difficulty Easy --state active --batch

# Available states: active, retired, all.
htb-cli challenges --state all --batch

2. Inspect it

Challenge names used by info, download, start, status, and stop must match exactly, ignoring letter case. An inexact name returns suggestions instead of silently selecting the wrong challenge.

htb-cli challenges info Bypass
htb-cli challenges info Bypass --json

The output includes the ID, category, difficulty, state, ownership, points, solves, release date, download availability, Docker requirement, and description.

3. Download and optionally extract it

# Saves to ./htb-challenges/Bypass/Bypass.zip and prints its SHA-256.
htb-cli challenges download Bypass

# Also extracts the archive using the standard HTB ZIP password.
htb-cli challenges download Bypass --extract

# Choose another base directory.
htb-cli challenges download Bypass --directory ~/Downloads/htb --extract

Downloads use a temporary file and do not replace an existing archive unless --force is supplied. Redirects must use HTTPS. Before extraction, the CLI rejects absolute paths, parent-directory traversal, backslash paths, and symbolic links. Extracted directories are restricted to the current user.

The optional --extract mode requires the unzip program because HTB archives can be password-protected. Its default password is hackthebox; use --password only when a specific archive uses a different one.

Treat downloaded Challenge files as untrusted. Inspect them in an isolated environment before executing them.

4. Manage a Docker instance

Challenges marked Docker: true can be started and stopped without opening the website:

# Create the instance.
htb-cli challenges start "Space Explorer" --batch

# Read its readiness state, expiration time, IP address, and exposed ports.
htb-cli challenges status "Space Explorer" --batch

# Release it when finished.
htb-cli challenges stop "Space Explorer" --batch

start refuses challenges that do not use a Docker instance. The lifecycle commands emit JSON so their output can be consumed by scripts. Poll status until play_info.status is ready before connecting, and always stop an unused instance.

5. Submit the flag

# The flag is requested without echoing it to the terminal.
htb-cli submit --challenge Bypass --batch

Avoid putting a real flag directly in shell history with --flag. After a successful submission, verify the OWNED column or the detailed JSON:

htb-cli challenges --difficulty Easy --state active --batch
htb-cli challenges info Bypass --json

The Activity section in htb-cli info --batch loads the 50 most recent profile events from the HTB v5 API.

The original documentation remains useful for the command overview, but some API-specific details predate this maintained fork: https://htb-cli-documentation.qu35t.pw/.

Contributing

Bug reports and pull requests are welcome. Do not include HTB tokens, VPN credentials, flags, or private lab material in reports or fixtures.

Credits and license

The original project was created and maintained by QU35T-code and contributors. This fork is maintained by PsyGuy007-sys.

Licensed under the GNU General Public License v3.0.