CLI

thq is the TunnelHQ command-line tool. Use it to test any VPN config, share link, or subscription URL from your terminal, manage monitors, Uptime checks, and API keys, and connect the MCP server to your AI editor. It runs on macOS, Linux, WSL, and Windows.

This page describes thq 0.4.0, the current release. Run thq --version to see yours.

Install

thq needs Node.js 20 or newer. Both installers check for Node.js and npm before installing.

macOS / Linux / WSL

Install on macOS, Linux, or WSL

curl -fsSL https://tunnelhq.com/install.sh | bash

Windows

In PowerShell 5.1 or newer:

Install on Windows

irm https://tunnelhq.com/install.ps1 | iex

Or install the package with npm directly:

Install on Windows with npm

npm install -g https://tunnelhq.com/releases/latest/tunnelhq-cli.tgz

Sign in

thq login uses the device flow: run the command, approve the request in your browser, and you’re signed in. There’s no token to copy. Your credentials are saved to ~/.thq/credentials.json.

Sign in

thq login

Option	Description
--no-browser	Don’t open the browser; print the approval URL instead.
--qr	Print a QR code for the approval URL. On by default when there’s no display, for example over SSH.
--no-qr	Don’t print the QR code.
--host <url>	Sign in to a different API host.

The approval is refused if your workspace’s plan doesn’t include API access, with the message “API access isn’t included on this workspace’s plan. Upgrade to use the CLI.”

The key thq login creates is an account-wide key, named “CLI · <computer name> · <date>”, which never expires.

thq logout removes the saved credentials and switches the key off on the server. The key stays on the API Keys page as Disabled; to delete it, choose Revoke there, or run thq keys revoke <id> --hard before you log out.

For CI and scripts, set an API key in the environment instead. When THQ_API_KEY is set, it’s used instead of the saved sign-in.

Use an API key in CI

export THQ_API_KEY="thk_..."

Requires a paid plan

The CLI uses the API, so it needs a plan with API access: Starter and above. See Getting an API key.

Test a config

thq test checks a VPN config on the spot and saves nothing. The target can be a config file path, a share link, a raw config string, or an https:// subscription URL.

Test a config, a share link, or a subscription

thq test ./wg0.conf
thq test 'vless://<uuid>@vpn.example.com:443?security=reality&...'
thq test https://provider.example.com/sub --first 5 --json

Option	Description
--json	Machine-readable output, for CI.
--protocol <name>	Force the protocol: wireguard, openvpn, ikev2, openconnect, vmess, vless, trojan, shadowsocks, amneziawg, hysteria2, or tuic.
--timeout <seconds>	How long to wait. Default 30, minimum 5, maximum 120.
--host <hostname>, --port <number>	Server host and port for IKEv2, OpenConnect, and OpenVPN (required for IKEv2 and OpenConnect). WireGuard, AmneziaWG, and share links use their own.
-u, --username; -p, --password	Override the credentials.
--remote-id <id>	Set the IKEv2 remote ID.
--engine <name>	Force an engine: singbox, xray, auto, both, or race. By default, the checker picks one per protocol.
--first <n>	Subscription URLs only: test the first n entries. Alias: --limit.
--index <n>	Subscription URLs only: test one entry, counting from 1.

A subscription URL tests every entry unless you pass --first or --index.

IKEv2 and OpenConnect don’t need a config: pass the server and the credentials.

Test IKEv2 without a config

thq test --protocol ikev2 --host vpn.example.com -u alice -p secret

thq test works out the protocol from, in order:

1. --protocol.
2. The URI scheme, such as vless:// or ss://.
3. The content: an [Interface] section is WireGuard, or AmneziaWG when it has Jc, Jmin, Jmax, or H1–H4 keys; client and remote lines are OpenVPN. So a .conf file that holds an OpenVPN config is tested as OpenVPN.
4. The file extension: .conf is WireGuard, .ovpn is OpenVPN.
5. An http:// or https:// address is a subscription URL.

thq test exits with 0 when the test passes and 1 when it fails, so you can use it in CI.

Tests run on the same checkers as scheduled monitors, through POST /check. They count toward your API rate limit, not your on-demand test quota.

Manage monitors

thq servers manages the project’s saved monitors. Every thq servers and thq checks command works in the project in THQ_PROJECT_ID, or the one you pass with --project <id>, and takes --json.

Command	Description
thq servers list	List monitors. --family chooses tunnel (the default), uptime, or all. Filter with --status, --protocol, --search, and --active-only; --limit defaults to 100.
thq servers create <input> --name <name>	Create a VPN monitor from a config file, share link, or raw config. It takes thq test’s connection options (--protocol, --host, --port, -u, -p, --remote-id), plus --proto udp or tcp for OpenVPN, --ip for a WireGuard or AmneziaWG config without an Endpoint line, --interval, --tag (repeat it for more), and --paused. For OpenConnect and IKEv2, leave out the input and pass --host, --username, and --password.
thq servers delete <id> --yes	Delete a monitor or an Uptime check by its ID, srv_123 or 123. --yes is always required, with --json too.

Create monitors

thq servers create wg.conf --name "WG Frankfurt"
thq servers create 'vless://<uuid>@host:443' --name "VLESS EU"
thq servers create '' --protocol openconnect --name "OC Corp" \
  --host vpn.example.com --username alice --password secret

Manage Uptime checks

thq checks list lists the project’s Uptime checks. Filter with --type, --status, --search, and --active-only; --limit defaults to 100.

thq checks create <target> --name <name> creates a check. Without --type, the target sets the type, the same way the dashboard does:

Target	Creates
https://example.com or example.com/health	A website check, with https:// added if it’s missing. With --keyword, a keyword check.
db.example.com:5432 or [2001:db8::1]:443	A TCP port check. --port overrides the port.
8.8.8.8 (an IP address)	A ping check.
example.com (a bare hostname)	A website check, with https:// added. Add --type ping to ping it instead.
1.1.1.1 --domain example.com	A DNS check. The target is the DNS server; --keyword is text the answer must contain.
No target, with --period	A heartbeat. The command prints the address your job calls.

Targets must be public addresses: private and reserved ones are refused.

Option	Description
--type <type>	http, keyword, ping, port, dns, or push (a heartbeat).
--keyword <text>	Keyword check: text the page must contain. DNS check: text the answer must contain.
--invert-keyword	Keyword check: alert when the text is found.
--accept <codes>	Website and keyword checks: accepted status codes, such as 200-299,301. Default 200-299.
--port <n>	TCP port check: the port.
--domain <name>	DNS check: the domain to ask about.
--period <seconds>	Heartbeat: the longest time between two calls from your job. Default 86400.
--grace <seconds>	Heartbeat: how late a call can be before it’s down. Default 3600.
--interval <seconds>	Seconds between checks. Left out, the recommended default.
--tag <name>	Add a tag. Repeat it for more.
--paused	Create the check paused.

Create Uptime checks

thq checks create https://example.com --name "Homepage"
thq checks create https://example.com/login --name "Login" --keyword "Sign in"
thq checks create db.example.com:5432 --name "Postgres"
thq checks create 1.1.1.1 --name "Resolver" --domain example.com
thq checks create --name "Nightly backup" --period 86400 --grace 3600

To change or pause a check, use the dashboard, the REST API, or the MCP server. To delete one, use thq servers delete.

Manage API keys

Command	Description
thq keys list	List your API keys.
thq keys create <name> [--expires <ISO date>]	Create a workspace key. Keys created this way start with uk. Needs a workspace key in THQ_API_KEY: the account-wide key from thq login is refused. An --expires value that isn’t a date, such as 31/12/2026, is refused.
thq keys revoke <id> [--hard]	Disable a key. With --hard, delete it permanently. The ID is the number, or the uk… form.

Set up the MCP server

thq mcp prints the configuration for the MCP server, or applies it for you.

Option	Description
--client <name>	claude, cursor, windsurf, or cline.
--apply	Apply the configuration: runs claude mcp add for Claude Code, or writes the JSON config for the other clients.
--update	With --client, clear TunnelHQ’s cached MCP server and add it to that client again, so your editor gets the current release on its next start. Without --client, it changes nothing.
--json	Print the configuration snippet and exit.
--api-key <value>	Use this key in the configuration.

Other commands

Command	Description
thq whoami	Show the account you’re signed in as.
thq doctor	Diagnose connection and authentication problems.
thq upgrade	Update the CLI. It detects whether you installed it with npm, Homebrew, or the install script. Alias: thq update.
thq install	Reinstall the CLI to a stable location and add it to your PATH.

Run thq --help for every command and option.

Interactive REPL

Run thq with no arguments in an interactive terminal to open the slash-command interface. It doesn’t open when input or output is redirected, or when NO_COLOR is set.

Command	Description
/test	Test a VPN config, share link, or subscription URL.
/whoami	Show your account, plan, and quota.
/keys	list, create <name>, or revoke <id>.
/mcp	Set up the MCP server.
/doctor	Diagnose connection and authentication problems.
/upgrade	Update the CLI.
/login, /logout	Sign in or out.
/help	List every command.
/exit	Quit.

Environment variables

Variable	Description
THQ_API_KEY	API key to use instead of the saved sign-in.
THQ_HOST	API host. Version 0.3.1 defaults to https://beta.tunnelhq.com.
THQ_PROJECT_ID	Default project.
THQ_ORG_ID	Default workspace.
THQ_HEADLESS	1 or 0 to force headless mode on or off.
THQ_SKIP_UPDATE_CHECK	1 to skip the background check for a newer version.
THQ_INSTALL_DIR	Where thq install puts the CLI. Defaults to ~/.local/bin, or %LOCALAPPDATA%\TunnelHQ\bin on Windows.