---

Your Hack The Box data, wherever you want it:

Terminal, Spreadsheets, Browser, or GitHub Profile Badges updated automatically via GitHub Actions.

---

Features

• CLI

  • A fast CLI for Hack The Box: list machines, submit flags, spawn/stop/reset labs, and view profile stats.
  • Built with Python, Rich UI, and optional Kitty terminal inline avatars.

• Metrics

  • Get detailed data of all your activity in hack the box; paths, tracks, ranks, everything

• Badges

  • Auto-generated profile badges for your GitHub README
  • 12 templates: classic, terminal, GitHub-style cards, minimal badge, and more
  • Public + optional auth: works with a public profile; app token unlocks extra API data
  • No fork required: copy a workflow template into your profile repo

• Dashboard

  • An interactive browser dashboard to visualize every Hack The Box machine you've completed
  • Searchable table of pwned machines with techniques, difficulty, OS, dates, and writeup links
  • Excel-driven updates.

Quick start

Install anywhere

bash scripts/install.sh
# or: curl -fsSL …/scripts/install.sh | bash

Manual equivalent:

mkdir -p "$HOME/.local/opt" "$HOME/.local/bin"
git clone https://github.com/yonasuriv/htb-ctrl.git "$HOME/.local/opt/htb-ctrl"
ln -sf "$HOME/.local/opt/htb-ctrl/htbctrl.py" "$HOME/.local/bin/htbctrl"
htbctrl --help

First run bootstraps .venv and dependencies silently. See Installation.

Development checkout

git clone https://github.com/yonasuriv/htb-ctrl.git && cd htb-ctrl
htbctrl --help

Copy examples/config/.env.example to .env and set HTB_PROFILE_ID, or pass -p on metrics commands.

Commands

Command	Description
htbctrl --help	Full command and flag reference
htbctrl auth --token …	Save HTB API token
htbctrl machines	List/search machines
htbctrl metrics pull …	Fetch profile data to user/<id>/data/
htbctrl badges generate …	Full badge workflow → user/<id>/badges/
htbctrl dashboard	Open dashboard offline
htbctrl dashboard --serve	Serve on http://127.0.0.1:8080
htbctrl dashboard --new-sheet	Create htb_machines.xlsx at repo root

Global flags: --from-env, --api-token, --bearer, --hide-banner. See Configuration.

User output layout:

user/
└── 780424/
    ├── data/      # cached HTB API JSON
    └── badges/    # generated PNG/SVG

CLI

htbctrl auth --token YOUR_TOKEN
htbctrl machines

Note

Kitty optional: Kitty enables inline machine avatars via kitten icat. Everything else works in any terminal.

Get a token at HTB Settings → API Key.

Badges

htbctrl metrics pull -p PROFILE_ID
htbctrl badges generate -p PROFILE_ID
htbctrl badges generate --from-env

Set the workflow in your profile without forking: Getting Started → GitHub Actions.

Dashboard

htbctrl dashboard --new-sheet
htbctrl dashboard --serve

Edit htb_machines.xlsx at the repo root as you pwn new boxes; reload the page to refresh.

Documentation

Full guide index: docs/guides/README.md

Area	Start here
Install & bootstrap	installation.md
Config (SSOT)	configuration.md
Terminal CLI	cli-getting-started.md
Badges	badge-getting-started.md
Dashboard	dashboard-getting-started.md

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

This project is not affiliated with, endorsed by, or associated with Hack The Box.

Credits

This work was heavily inspired by the following authors:

• Lowlighter
• D1se0
• K-4yser