CLI Reference

Every command is a noun and a verb: hle tunnel create, hle daemon install, hle auth login. The nouns:

Command	What it does
hle tunnel	Create, inspect and secure tunnels.
hle agent	Run a multi-tunnel agent controlled from the dashboard.
hle daemon	Install and manage background services (systemd/launchd/rc.d).
hle auth	Manage API key authentication.
hle status	What this machine is set up to do, on one screen.
hle update	Update the HLE client to the latest version (any install method).
hle version	Print the installed version.
hle firepuncher	Forward TCP ports from a remote agent to this machine.

The guides below explain what each noun is for. The Command reference lists every command with its arguments, options and defaults. That reference and the Environment Variables page are generated from the CLI itself, so they match the version of the client the docs were built against.

Tunnel-scoped subcommands under hle tunnel accept a label (resolved to <label>-<user_code> via /api/auth/me) or a full subdomain. For example, hle tunnel get ha and hle tunnel get ha-x7k both work.

Every command that reads a resource accepts -o json for scripting.

hle tunnel create

Expose a local service to the internet.

hle tunnel create myapp http://localhost:8080

Expose and allow specific users in one command:

hle tunnel create app http://localhost:8080 --allow user@gmail.com --allow google:friend@gmail.com

--allow is additive — it adds rules without removing existing ones. Use hle tunnel access replace for a declarative reconcile.

See tunnel create for every option.

hle tunnel webhook

Create a webhook tunnel for receiving HTTP callbacks (GitHub, Stripe, etc.). Disables the SSO gate and WebSocket, enforces path prefix filtering.

hle tunnel webhook --path /hook/github --forward-to http://localhost:3000 --label gh

See the Webhooks guide for security, rate limits, and provider setup.

hle agent

Run a single process that serves every endpoint you declare in the dashboard. See the Agent guide for the full walkthrough.

hle auth login --agent-token   # Save an agent token (prompts for it)
hle agent run                  # Connect and serve the dashboard's endpoints
hle agent list                 # List your agents and whether they're online
hle agent status               # Show where the token is coming from
hle agent services             # List services this machine could expose
hle agent logout               # Remove the saved token

The token is resolved in this order: --token flag > HLE_AGENT_TOKEN env var > ~/.config/hle/agent.toml. It is separate from your API key.

agent list is the odd one out: it asks the relay about your whole account rather than inspecting this machine, so it authenticates with your API key, not the agent token. It’s the quickest way to find the name to pass to hle firepuncher:

$ hle agent list
                          Agents
┏━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┓
┃ Name     ┃ Status  ┃ Endpoints ┃ Version ┃ Last seen ┃
┡━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━┩
│ trikala  │ online  │         2 │ 2607.7  │ 4s ago    │
│ nas      │ offline │         1 │ 2607.5  │ 3h ago    │
└──────────┴─────────┴───────────┴─────────┴───────────┘

Add --json for scripting.

hle agent services

Lists the Kubernetes Services and Docker containers this machine can see and could expose. Runs the same read-only scan the agent reports to the dashboard, so it’s useful for checking what an agent would find before enrolling it. See Service discovery.

hle agent services
hle agent services --provider docker
hle agent services --json

The reported address is the URL the agent would use to reach the service, not a public URL.

hle firepuncher

Forward a TCP port that a remote agent can reach to a port on this machine — SSH, Postgres, RDP, anything TCP — without opening a port anywhere. See the Firepuncher guide.

hle firepuncher rpi 22 --port 9922      # then: ssh -p 9922 root@localhost
hle firepuncher nas 192.168.1.50:5432   # postgres on the agent's LAN

The target is resolved by the agent, not by this machine: a bare port means the agent’s own loopback, and host:port means that host as the agent sees it. The port you connect to locally is the --port one.

Run a command and tear the forwards down when it exits. In the command, {port} is the first local port and {port1}, {port2}, … are each forward’s, so a derived port needn’t be guessed. The same values arrive as HLE_FP_PORT and HLE_FP_PORT_1, HLE_FP_PORT_2, … for scripts. The exit status is the command’s.

hle firepuncher rpi 22 -- ssh -p '{port}' me@127.0.0.1
hle firepuncher rpi 22 5432 -- ./backup.sh

The agent refuses targets that aren’t in its allowlist. By default that is every network the agent is attached to (its LAN, Docker, Kubernetes, any VPN) but not the public internet; widen or narrow it per agent in the dashboard under Connections → Firepuncher.

hle daemon

Install a tunnel, the agent or a forward as a background service — systemd on Linux, launchd on macOS — so it survives reboots and restarts on failure.

# The agent (all endpoints from the dashboard)
hle daemon install agent

# A single fixed tunnel
hle daemon install tunnel ha http://localhost:8123

# A firepuncher forward, always available locally
hle daemon install firepuncher rpi 22 --port 9922

hle daemon status agent      # or the tunnel's label: ha
hle daemon list
hle daemon logs agent
hle daemon delete agent

Credentials are never written into the service definition. They’re read at runtime from the running user’s ~/.config/hle/ (config.toml for the API key, agent.toml for the agent token) or from HLE_API_KEY / HLE_AGENT_TOKEN.

daemon install tunnel accepts the same options as tunnel create (--zone, --apex, --auth, --allow, …) and bakes them into the unit.

Scope auto-detection: running as root installs a system service (starts at boot), a normal user gets a per-user one. A per-user systemd service stops at logout unless you run sudo loginctl enable-linger $USER.

hle auth

Manage the API key the CLI uses to talk to the relay.

hle auth login                    # Interactive (opens dashboard)
hle auth login --api-key <KEY>    # Non-interactive
hle auth status                   # Show current key source
hle auth logout                   # Remove saved key

The key is resolved in this order: --api-key flag > HLE_API_KEY env var > ~/.config/hle/config.toml.

hle tunnel

All tunnel and account configuration lives under hle tunnel. The management commands share one set of verbs: list, get, create, set, delete.

hle tunnel list

List active tunnels for your account.

hle tunnel list

hle tunnel get

Show the full configuration and live state for a tunnel — auth mode, access rules, PIN, basic-auth, and connection state — in one call.

hle tunnel get ha
hle tunnel get ha-x7k    # full subdomain also accepted

hle tunnel set

Change a tunnel’s SSO gate. The tunnel must have been registered at least once. Webhook tunnels are always public and cannot be changed.

hle tunnel set ha --auth sso     # SSO gate on
hle tunnel set ha --auth none    # tunnel becomes public

hle tunnel delete

Delete a tunnel’s record. A tunnel that is connected is refused: stop the client first.

hle tunnel delete ha

hle tunnel access — SSO email allow-list

hle tunnel access list ha                                  # List rules
hle tunnel access create ha friend@example.com             # Allow an email
hle tunnel access create ha dev@co.com --provider github   # Require GitHub SSO
hle tunnel access delete ha 42                             # Remove rule by ID

Declarative reconcile

hle tunnel access replace is declarative: rules already on the server but not in the args are removed. Useful for IaC / CI/CD where the args are the source of truth.

hle tunnel access replace ha google:alice@example.com github:dev@co.com
hle tunnel access replace ha --clear     # Remove all rules

Compare with hle tunnel create --allow, which only adds.

hle tunnel pin — PIN access control

hle tunnel pin set ha       # Set 4-8 digit PIN (prompts)
hle tunnel pin get ha       # Check whether a PIN is active
hle tunnel pin delete ha    # Remove PIN

hle tunnel basic-auth — HTTP Basic Auth

Replaces SSO and PIN with a username/password prompt enforced by the relay.

hle tunnel basic-auth set ha       # Prompts for username + password (min 8 chars)
hle tunnel basic-auth get ha       # Show whether active and the username
hle tunnel basic-auth delete ha    # Remove credentials

hle tunnel share — temporary share links

hle tunnel share create ha                        # 24h link (default)
hle tunnel share create ha --duration 1h          # 1-hour link
hle tunnel share create ha --max-uses 5           # Limited uses
hle tunnel share create ha --name "demo"          # Name for reference
hle tunnel share list ha                          # List share links
hle tunnel share delete ha 42                     # Revoke a link by ID

Compatibility profiles

The relay proxies your service as it is: the headers it sends are the headers your browser gets, and the HTML it serves is the HTML your browser gets.

Home Assistant is the exception. It needs its service worker replaced, a small script added to its pages, and X-Frame-Options removed, or its frontend caches the wrong thing and its addon iframes break through a tunnel. The relay applies those fixes to Home Assistant tunnels only, and recognises them from the service URL — port 8123, or a hostname like homeassistant.local.

If your Home Assistant sits somewhere that doesn’t look like that (behind a reverse proxy on :443, say), name it:

hle tunnel create ha https://ha.internal.example --option compat=homeassistant

The reverse also works — --option compat=generic turns the fixes off for a tunnel that would otherwise be detected as Home Assistant, leaving its responses untouched.

Global options

These apply to every command, and may be written before or after the subcommand. Commands that talk to the relay also take their own --api-key; it is resolved in the order given under Config file.

Option	Default	Description
--version		Show the version and exit.
--debug		Enable debug logging
--api-key TEXT		API key. Also read from HLE_API_KEY, then ~/.config/hle/config.toml.
-o, --output OUTPUT	table	Output format. ‘json’ prints the resource and nothing else. One of table, json.
-q, --quiet		Only print errors.
--no-color		Disable colour (also NO_COLOR=1).
--no-input		Never prompt; fail instead. For scripts and unattended runs.

Command reference

Generated from the CLI. [OPTIONS] in a usage line means any of the options in the table beneath it.

tunnel

Create, inspect and secure tunnels.

Examples:

hle tunnel create ha http://localhost:8123  # Run a tunnel
hle tunnel list  # What is published
hle tunnel get ha  # One tunnel, in full
hle tunnel set ha --auth none  # Make it public
hle tunnel access create ha you@example.com  # Let someone in
hle tunnel delete ha  # Remove the record

Usage: hle tunnel [OPTIONS] COMMAND [ARGS]...

Subcommand	What it does
tunnel access	Manage tunnel access allow-list (SSO email rules).
tunnel basic-auth	Manage tunnel HTTP Basic Auth access control.
tunnel create	Expose a local service to the internet.
tunnel delete	Delete a tunnel’s record.
tunnel get	Show full configuration and live state for a tunnel.
tunnel list	List active tunnels for your account.
tunnel pin	Manage tunnel PIN access control.
tunnel preflight	Check whether SERVICE_URL will work as a tunnel, before creating one.
tunnel set	Change a published tunnel’s settings.
tunnel share	Manage temporary share links for a tunnel.
tunnel webhook	Forward incoming webhooks to a local service.

tunnel access

Manage tunnel access allow-list (SSO email rules).

Usage: hle tunnel access [OPTIONS] COMMAND [ARGS]...

Subcommand	What it does
tunnel access create	Add an email to a tunnel’s access allow-list.
tunnel access delete	Remove an access rule by ID.
tunnel access list	List access rules for a tunnel.
tunnel access replace	Reconcile a tunnel’s access allow-list to exactly SPECS.

tunnel access create

Add an email to a tunnel’s access allow-list.

Usage: hle tunnel access create [OPTIONS] LABEL EMAIL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).
EMAIL	email or provider:email; the provider defaults to any.

Option	Default	Description
--provider PROVIDER	any	Required auth provider. One of any, google, github, hle.
--api-key TEXT		API key for authentication. Env: HLE_API_KEY.

tunnel access delete

Remove an access rule by ID.

Usage: hle tunnel access delete [OPTIONS] LABEL RULE_ID

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).
RULE_ID	ID from hle tunnel access list.

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel access list

List access rules for a tunnel.

Usage: hle tunnel access list [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel access replace

Reconcile a tunnel’s access allow-list to exactly SPECS.

Usage: hle tunnel access replace [OPTIONS] LABEL [SPECS]...

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).
SPECS	[provider:]email rules that should be the whole allow-list. None with --clear empties it.

Option	Description
--clear	Remove all rules (no specs allowed)
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel basic-auth

Manage tunnel HTTP Basic Auth access control.

Usage: hle tunnel basic-auth [OPTIONS] COMMAND [ARGS]...

Subcommand	What it does
tunnel basic-auth delete	Remove HTTP Basic Auth from a tunnel.
tunnel basic-auth get	Show HTTP Basic Auth status for a tunnel.
tunnel basic-auth set	Set HTTP Basic Auth credentials for a tunnel.

tunnel basic-auth delete

Remove HTTP Basic Auth from a tunnel.

Usage: hle tunnel basic-auth delete [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel basic-auth get

Show HTTP Basic Auth status for a tunnel.

Usage: hle tunnel basic-auth get [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel basic-auth set

Set HTTP Basic Auth credentials for a tunnel.

Usage: hle tunnel basic-auth set [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel create

Expose a local service to the internet.

Examples:

hle tunnel create ha http://localhost:8123
hle tunnel create jellyfin http://192.168.1.10:8096 --allow you@example.com
hle tunnel create --apex --zone zone.example http://localhost:3000

Usage: hle tunnel create [OPTIONS] [LABEL] URL

Argument	Description
LABEL	Name the tunnel is published under: the ha of ha-x7k.hle.world. Optional: given only a URL, the label is chosen for you.
URL	The local service, e.g. http://localhost:8080.

Option	Default	Description
--api-key TEXT		API key. Defaults to the root —api-key.
--zone TEXT		Custom zone to publish under (e.g. zone.example). Required for —apex.
--auth AUTH	sso	Auth mode. One of sso, none.
--websocket / --no-websocket	on	Enable WebSocket proxying
--verify-ssl		Enable SSL certificate verification (by default self-signed certs are accepted)
--forward-host		Forward the browser’s Host header to the local service (for services that validate Host).
--upstream-basic-auth USER:PASS		Inject Basic Auth into every request to the local service. Format: USER:PASS. Env: HLE_UPSTREAM_BASIC_AUTH.
--apex		Serve at the bare zone root (e.g. https://zone.example) instead of a subdomain.
--option KEY=VALUE		Generic server-interpreted parameter, passed through verbatim. Repeatable. The server defines which keys are valid. Example: —option zone=zone.example
--response-timeout SECONDS		Seconds the relay waits for the local service to respond (default 30, webhooks 120, max 1200).
--allow [PROVIDER:]EMAIL		Allow an email to access this tunnel via SSO. Format: ‘email’ or ‘provider:email’. Providers: any (default), google, github, hle. Repeatable.
--events EVENTS		Write machine-readable events to stdout, one JSON object per line (registered, connected, disconnected, notice, error, fatal); human output moves to stderr. Schema: docs/events.md. One of jsonl.

tunnel delete

Delete a tunnel’s record.

Example:

hle tunnel delete ha

Usage: hle tunnel delete [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
-y, --yes	Do not ask for confirmation.
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel get

Show full configuration and live state for a tunnel.

Example:

hle tunnel get ha
hle tunnel get ha -o json

Usage: hle tunnel get [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel list

List active tunnels for your account.

Example:

hle tunnel list
hle tunnel list -o json | jq '.[].subdomain'

Usage: hle tunnel list [OPTIONS]

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel pin

Manage tunnel PIN access control.

Usage: hle tunnel pin [OPTIONS] COMMAND [ARGS]...

Subcommand	What it does
tunnel pin delete	Remove the PIN for a tunnel.
tunnel pin get	Show PIN status for a tunnel.
tunnel pin set	Set a PIN for a tunnel (prompts for 4-8 digit PIN).

tunnel pin delete

Remove the PIN for a tunnel.

Usage: hle tunnel pin delete [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel pin get

Show PIN status for a tunnel.

Usage: hle tunnel pin get [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel pin set

Set a PIN for a tunnel (prompts for 4-8 digit PIN).

Usage: hle tunnel pin set [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel preflight

Check whether SERVICE_URL will work as a tunnel, before creating one.

Usage: hle tunnel preflight [OPTIONS] SERVICE_URL

Argument	Description
SERVICE_URL	The local service to probe.

Option	Description
--host TEXT	Hostname the tunnel will be reached by
--verify-ssl	Verify the upstream certificate
--no-websocket	Check as WebSockets-disabled
--forward-host	Check as host-forwarding
--json	Machine-readable output

tunnel set

Change a published tunnel’s settings.

Example:

hle tunnel set ha --auth sso  # SSO gate on
hle tunnel set ha --auth none  # Anyone with the URL gets in

Usage: hle tunnel set [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--auth AUTH	Gate mode: sso (visitors sign in) or none (public). One of sso, none.
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel share

Manage temporary share links for a tunnel.

Usage: hle tunnel share [OPTIONS] COMMAND [ARGS]...

Subcommand	What it does
tunnel share create	Create a temporary share link for a tunnel.
tunnel share delete	Revoke a share link by ID.
tunnel share list	List share links for a tunnel.

tunnel share create

Create a temporary share link for a tunnel.

Usage: hle tunnel share create [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Default	Description
--duration DURATION	24h	Link validity duration. One of 1h, 24h, 7d.
--name TEXT		Optional name for the link
--max-uses INTEGER		Maximum number of uses
--api-key TEXT		API key for authentication. Env: HLE_API_KEY.

tunnel share delete

Revoke a share link by ID.

Usage: hle tunnel share delete [OPTIONS] LABEL LINK_ID

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).
LINK_ID	ID from hle tunnel share list.

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel share list

List share links for a tunnel.

Usage: hle tunnel share list [OPTIONS] LABEL

Argument	Description
LABEL	Tunnel label (ha) or full subdomain (ha-x7k).

Option	Description
--api-key TEXT	API key for authentication. Env: HLE_API_KEY.

tunnel webhook

Forward incoming webhooks to a local service.

Usage: hle tunnel webhook [OPTIONS]

Option	Default	Description
--path TEXT	required	Webhook path (e.g. /webhook/github)
--forward-to TEXT	required	Local URL to forward webhooks to
--label TEXT	required	Webhook label (e.g. github-hook)
--api-key TEXT		API key. Falls back to ~/.config/hle/config.toml if not set. Env: HLE_API_KEY.
--response-timeout SECONDS		Seconds the relay waits for the local service to respond (default 30, webhooks 120, max 1200).
--events EVENTS		Write machine-readable events to stdout, one JSON object per line (registered, connected, disconnected, notice, error, fatal); human output moves to stderr. Schema: docs/events.md. One of jsonl.

agent

Run a multi-tunnel agent controlled from the dashboard.

Usage: hle agent [OPTIONS] COMMAND [ARGS]...

Subcommand	What it does
agent list	List the agents on your account, and whether they’re online.
agent logout	Remove the saved agent token.
agent run	Run the agent: connect, fetch endpoints from the dashboard, and reconcile.
agent services	List services this machine can see and could expose.
agent status	Show whether an agent token is configured.

agent list

List the agents on your account, and whether they’re online.

Usage: hle agent list [OPTIONS]

Option	Description
--api-key TEXT	API key (also reads HLE_API_KEY env var, then ~/.config/hle/config.toml)
--json	Machine-readable output

agent logout

Remove the saved agent token.

Usage: hle agent logout [OPTIONS]

agent run

Run the agent: connect, fetch endpoints from the dashboard, and reconcile.

Usage: hle agent run [OPTIONS]

Option	Description
--token TEXT	Agent token (overrides saved) Env: HLE_AGENT_TOKEN.
--relay-host TEXT	Relay host
--relay-port INTEGER	Relay port
--events EVENTS	Write machine-readable events to stdout, one JSON object per line (registered, connected, disconnected, notice, error, fatal); human output moves to stderr. Schema: docs/events.md. One of jsonl.

agent services

List services this machine can see and could expose.

Usage: hle agent services [OPTIONS]

Option	Description
--provider TEXT	Only show one provider (k8s, docker)
--json	Machine-readable output

agent status

Show whether an agent token is configured.

Usage: hle agent status [OPTIONS]

Option	Description
--ready	Exit 0 only if the running agent is connected (for readiness probes).

daemon

Install and manage background services (systemd/launchd/rc.d).

Examples:

hle daemon install tunnel ha http://localhost:8123
hle daemon install agent
hle daemon list
hle daemon logs agent

Usage: hle daemon [OPTIONS] COMMAND [ARGS]...

Subcommand	What it does
daemon delete	Stop, disable, and remove a background service.
daemon install	Install and start a background service.
daemon list	List installed hle services, in both scopes by default.
daemon logs	Show a service’s log.
daemon refresh	Rebuild a service file against the installed client, then start it.
daemon restart	Restart a background service, or all of them with —all.
daemon status	Show status for a background service.

daemon delete

Stop, disable, and remove a background service.

Examples:

hle daemon delete ha
hle daemon delete agent --user

Usage: hle daemon delete [OPTIONS] NAME

Argument	Description
NAME	Service name, e.g. agent, or a tunnel’s label. Optional with --all.

Option	Description
--user	Target a per-user service
--system	Target a system service

daemon install

Install and start a background service.

Usage: hle daemon install [OPTIONS] COMMAND [ARGS]...

Subcommand	What it does
daemon install agent	Install the dashboard-driven agent.
daemon install firepuncher	Install a permanent forward from a remote port to this machine.
daemon install tunnel	Install one always-on tunnel.

daemon install agent

Install the dashboard-driven agent.

Example:

hle daemon install agent

Usage: hle daemon install agent [OPTIONS]

Option	Default	Description
--relay-host TEXT		Relay host (default hle.world)
--relay-port INTEGER		Relay port (default 443)
--start / --no-start	on	Enable + start it now
--run-as TEXT		System service user
--system		Install a system-wide service
--user		Install a per-user service
--name TEXT		Override the unit/plist name

daemon install firepuncher

Install a permanent forward from a remote port to this machine.

Example:

hle daemon install firepuncher rpi 22 --port 9922
hle daemon install firepuncher rpi 192.168.1.50:8006 --port 8006

Usage: hle daemon install firepuncher [OPTIONS] AGENT_NAME TARGET

Argument	Description
TARGET	Service name, e.g. agent, or a tunnel’s label. Optional with --all.

Option	Default	Description
--port INTEGER		Local port to bind
--bind TEXT		Local address to bind
--relay-host TEXT		Relay host (default hle.world)
--relay-port INTEGER		Relay port (default 443)
--start / --no-start	on	Enable + start it now
--run-as TEXT		System service user
--system		Install a system-wide service
--user		Install a per-user service
--name TEXT		Override the unit/plist name

daemon install tunnel

Install one always-on tunnel.

Example:

hle daemon install tunnel ha http://localhost:8123
hle daemon install tunnel ha http://localhost:8123 --system --run-as ian

Usage: hle daemon install tunnel [OPTIONS] LABEL URL

Argument	Description
LABEL	Name the tunnel is published under.
URL	The local service, e.g. http://localhost:8123.

Option	Default	Description
--zone TEXT		Custom zone to publish under (e.g. zone.example). Required for —apex.
--auth AUTH	sso	Auth mode. One of sso, none.
--websocket / --no-websocket	on	Enable WebSocket proxying
--verify-ssl		Enable SSL certificate verification (by default self-signed certs are accepted)
--forward-host		Forward the browser’s Host header to the local service (for services that validate Host).
--upstream-basic-auth USER:PASS		Inject Basic Auth into every request to the local service. Format: USER:PASS. Env: HLE_UPSTREAM_BASIC_AUTH.
--apex		Serve at the bare zone root (e.g. https://zone.example) instead of a subdomain.
--option KEY=VALUE		Generic server-interpreted parameter, passed through verbatim. Repeatable. The server defines which keys are valid. Example: —option zone=zone.example
--response-timeout SECONDS		Seconds the relay waits for the local service to respond (default 30, webhooks 120, max 1200).
--allow [PROVIDER:]EMAIL		Allow an email to access this tunnel via SSO. Format: ‘email’ or ‘provider:email’. Providers: any (default), google, github, hle. Repeatable.
--start / --no-start	on	Enable + start it now
--run-as TEXT		System service user
--system		Install a system-wide service
--user		Install a per-user service
--name TEXT		Override the unit/plist name

daemon list

List installed hle services, in both scopes by default.

Usage: hle daemon list [OPTIONS]

Option	Description
--user	Only per-user services
--system	Only system services

daemon logs

Show a service’s log.

Examples:

hle daemon logs agent
hle daemon logs ha -n 200
hle daemon logs agent -f

Usage: hle daemon logs [OPTIONS] NAME

Argument	Description
NAME	Service name, e.g. agent, or a tunnel’s label. Optional with --all.

Option	Default	Description
--user		Target a per-user service
--system		Target a system service
-n, --lines INTEGER	50	How many lines to show
-f, --follow		Keep printing new lines

daemon refresh

Rebuild a service file against the installed client, then start it.

Usage: hle daemon refresh [OPTIONS] NAME

Argument	Description
NAME	Service name, e.g. agent, or a tunnel’s label. Optional with --all.

Option	Description
--all	Refresh every hle service

daemon restart

Restart a background service, or all of them with —all.

Usage: hle daemon restart [OPTIONS] NAME

Argument	Description
NAME	Service name, e.g. agent, or a tunnel’s label. Optional with --all.

Option	Description
--all	Restart every hle service

daemon status

Show status for a background service.

Examples:

hle daemon status agent
hle daemon status ha --user

Usage: hle daemon status [OPTIONS] NAME

Argument	Description
NAME	Service name, e.g. agent, or a tunnel’s label. Optional with --all.

Option	Description
--user	Target a per-user service
--system	Target a system service

auth

Manage API key authentication.

Usage: hle auth [OPTIONS] COMMAND [ARGS]...

Subcommand	What it does
auth login	Paste any key from the dashboard; HLE works out which kind it is.
auth logout	Remove the saved API key from ~/.config/hle/config.toml.
auth status	Show which credentials this machine has, and where they came from.

auth login

Paste any key from the dashboard; HLE works out which kind it is.

Examples:

hle auth login  # Paste any key from the dashboard

Usage: hle auth login [OPTIONS] [CREDENTIAL]

Option	Description
--api-key TEXT	The credential to save (alias for CREDENTIAL).
--force	Replace an existing agent token on this machine.

auth logout

Remove the saved API key from ~/.config/hle/config.toml.

Usage: hle auth logout [OPTIONS]

auth status

Show which credentials this machine has, and where they came from.

Usage: hle auth status [OPTIONS]

status

What this machine is set up to do, on one screen.

Example:

hle status
hle status -o json

Usage: hle status [OPTIONS]

update

Update the HLE client to the latest version (any install method).

Usage: hle update [OPTIONS]

Option	Description
--check	Only report current vs. latest; don’t upgrade.
--version TEXT	Upgrade/downgrade to this version
-y, --yes	Skip the confirmation prompt.

version

Print the installed version.

Usage: hle version [OPTIONS]

firepuncher

Forward TCP ports from a remote agent to this machine.

Examples:

hle firepuncher rpi 22 --port 9922        # then: ssh -p 9922 root@localhost
hle firepuncher nas 192.168.1.50:5432     # postgres on the agent's LAN
hle firepuncher rpi 22 nas:445            # two forwards, one command

Run a command and tear the forwards down when it exits:

hle firepuncher rpi 22 -- ssh -p '{port}' me@127.0.0.1
hle firepuncher rpi 22 5432 -- ./backup.sh

Usage: hle firepuncher [OPTIONS] AGENT TARGET... [-- COMMAND...]

Option	Default	Description
--agent TEXT		Agent to forward through (or the first argument)
--to HOST:PORT		Target as seen by the agent (e.g. localhost:22, or just 22). Repeatable.
--port INTEGER		Local port to listen on. Repeatable; paired with —to in order. Any not given are derived from the target port.
--bind TEXT	127.0.0.1	Local address to bind (default loopback — think before widening)
--api-key TEXT		API key (also reads HLE_API_KEY env var, then ~/.config/hle/config.toml)
--relay-host TEXT		Relay host
--relay-port INTEGER		Relay port

Config file

Save your API key in the config file:

api_key = "<your-api-key>"

Location: ~/.config/hle/config.toml

The API key is resolved in order: --api-key flag > HLE_API_KEY env var > config file.

Every environment variable the client reads is listed on the Environment Variables page.

Examples

Expose Home Assistant with a label:

hle tunnel create ha http://localhost:8123

Expose a development app without authentication:

hle tunnel create dev http://localhost:3000 --auth none

Expose and allow specific users in one command:

hle tunnel create ha http://localhost:8123 --allow user@gmail.com --allow google:friend@gmail.com

List your active tunnels:

hle tunnel list

Add a friend to your tunnel’s access list:

hle tunnel access create ha friend@example.com

Require GitHub login for a specific email:

hle tunnel access create ha colleague@work.com --provider github

View and remove access rules:

hle tunnel access list ha
hle tunnel access delete ha 42

Reconcile the allow-list to exactly two people (removes anyone else):

hle tunnel access replace ha google:alice@example.com github:bob@co.com

Set a PIN for quick access:

hle tunnel pin set ha

Create a temporary share link (expires in 1 hour, max 5 uses):

hle tunnel share create ha --duration 1h --max-uses 5

Protect a tunnel with HTTP Basic Auth:

hle tunnel basic-auth set ha
hle tunnel basic-auth get ha

Expose a service that itself requires credentials (inject upstream auth):

hle tunnel create ha http://localhost:8123 --upstream-basic-auth admin:yourpassword