CLI Reference

The HLE CLI has four top-level commands:

• hle expose — run a tunnel for a local service
• hle webhook — run a webhook forwarder
• hle auth — manage your API key
• hle config — configure tunnels (auth mode, access rules, PIN, basic-auth, share links, list)

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

hle expose

Expose a local service to the internet.

hle expose --service http://localhost:8080 --label myapp

Expose and allow specific users in one command:

hle expose --service http://localhost:8080 --label app \
  --allow user@gmail.com --allow google:friend@gmail.com

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

hle webhook

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

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

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

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 config

All tunnel and account configuration lives under hle config.

hle config list

List active tunnels for your account.

hle config list

hle config show

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

hle config show ha
hle config show ha-x7k    # full subdomain also accepted

hle config auth-mode

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 config auth-mode ha --set sso     # SSO gate on
hle config auth-mode ha --set none    # tunnel becomes public

hle config access — SSO email allow-list

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

Declarative reconcile

hle config 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 config access replace ha google:alice@example.com github:dev@co.com
hle config access replace ha --clear     # Remove all rules

Compare with hle expose --allow, which only adds.

hle config pin — PIN access control

hle config pin set ha       # Set 4-8 digit PIN (prompts)
hle config pin status ha    # Check whether a PIN is active
hle config pin remove ha    # Remove PIN

hle config basic-auth — HTTP Basic Auth

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

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

hle config share — temporary share links

hle config share create ha                        # 24h link (default)
hle config share create ha --duration 1h          # 1-hour link
hle config share create ha --max-uses 5           # Limited uses
hle config share create ha --label "demo"         # Label for reference
hle config share list ha                          # List share links
hle config share revoke ha 42                     # Revoke a link by ID

Flags for expose

Flag	Type	Default	Description
--service	string	required	Local service URL (e.g., http://localhost:8080)
--label	string	required	Service label for the subdomain (e.g., ha, jellyfin, app1)
--auth	enum	sso	Authentication mode: sso (OIDC) or none (public)
--api-key	string	—	API key. Also checked in HLE_API_KEY env var and config file
--websocket	boolean	enabled	Enable WebSocket proxying. Use --no-websocket to disable
--allow	string	—	Allow an email (additive). Format: email or provider:email. Providers: any (default), google, github, hle. Repeatable
--verify-ssl	boolean	false	Enable SSL certificate verification for the local service
--upstream-basic-auth	string	—	Inject Authorization: Basic into every request forwarded to the local service. Format: USER:PASS
--forward-host	boolean	false	Forward the browser’s Host header to the local service

Flags for webhook

Flag	Type	Default	Description
--path	string	required	Webhook path prefix (e.g. /hook/github). Cannot be /. Only requests matching this prefix are forwarded
--forward-to	string	required	Local URL to forward webhooks to
--label	string	required	Webhook label, e.g. github-hook
--api-key	string	—	API key. Also checked in HLE_API_KEY env var and config file

Flags for config access add

Flag	Type	Default	Description
--provider	enum	any	Required auth provider: any, google, github, or hle

Flags for config access replace

Positional arguments are [provider:]email specs (repeatable). Add --clear with no specs to remove all rules.

Flags for config share create

Flag	Type	Default	Description
--duration	enum	24h	Link validity: 1h, 24h, or 7d
--label	string	—	Optional label for the link
--max-uses	int	unlimited	Maximum number of uses

Global flags

These flags apply to all commands:

Flag	Type	Default	Description
--version	—	—	Show the client version and exit
--debug	boolean	false	Enable debug logging to stderr

Common flags

All commands that talk to the server (everything under hle config, plus hle expose and hle webhook) accept:

Flag	Type	Default	Description
--api-key	string	—	API key for authentication. Also checked in HLE_API_KEY env var and ~/.config/hle/config.toml

Config file

Save your API key in the config file:

api_key = "hle_your_32_char_hex_key"

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

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

Examples

Expose Home Assistant with a label:

hle expose --service http://localhost:8123 --label ha

Expose a development app without authentication:

hle expose --service http://localhost:3000 --label dev --auth none

Expose and allow specific users in one command:

hle expose --service http://localhost:8123 --label ha \
  --allow user@gmail.com --allow google:friend@gmail.com

List your active tunnels:

hle config list

Add a friend to your tunnel’s access list:

hle config access add ha friend@example.com

Require GitHub login for a specific email:

hle config access add ha colleague@work.com --provider github

View and remove access rules:

hle config access list ha
hle config access remove ha 42

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

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

Set a PIN for quick access:

hle config pin set ha

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

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

Protect a tunnel with HTTP Basic Auth:

hle config basic-auth set ha
hle config basic-auth status ha

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

hle expose --service http://localhost:8123 --label ha \
  --upstream-basic-auth admin:yourpassword