htb-cli 0.1.6

Hack The Box CLI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

# htb-cli

A terminal client for [Hack The Box](https://hackthebox.com). Browse machines, challenges, Sherlocks, and seasons. Spawn instances, submit flags, manage VPN connections.

Works with any HTB account (free or VIP).

## Install

```bash
cargo install htb-cli
```

Or download a binary from [releases](https://github.com/Saturate/HTB-CLI/releases).

## Setup

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

# Verify it works
htb auth status
```

## Usage

```bash
# 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.

```bash
# 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](https://ctf.hackthebox.com).

## Output

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

```bash
htb machines list --json
htb auth status --json
```

## MCP Server

Run as an [MCP](https://modelcontextprotocol.io) server for AI agent integration:

```bash
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

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

## Config

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

```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