CLI reference

Look up every hrzn command, option and environment variable. For a first tunnel, start with Getting started.

InstallCopy Anchor Link

npm install -g @hrzn/cli

The package adds two binaries, hrzn and horizon. They run the same CLI. This reference uses hrzn.

Global optionsCopy Anchor Link

These work on every command.

Before each command runs, the CLI checks the latest published version. When a newer version exists, it prints a warning and carries on:

HORIZON: Horizon 0.18.1 is available, you are on 0.18.0. Update with: npm install --global @hrzn/cli

When the latest version has a higher major number than yours, the CLI stops with exit code 1 and prints:

HORIZON: Horizon 0.18.0 is no longer supported. Install 1.0.0 to continue: npm install --global @hrzn/cli

If the check can't reach Horizon, the command runs without it.

hrzn loginCopy Anchor Link

Sign in to your Horizon account. The command prints an approval link, waits while you approve it in your browser, then stores your credentials in .hrznrc in your home folder (_hrznrc on Windows).

hrzn login <account-id>

Your dashboard shows the command with your account ID filled in.

The command has no options.

HORIZON: Approve the sign-in in your browser: <approval-link>
HORIZON: Signed in. Run hrzn tunnel http://localhost:3000 to start a tunnel.

Other outcomes, each with exit code 1 except the first:

hrzn logoutCopy Anchor Link

Sign out of your Horizon account. The command clears the stored credentials.

hrzn logout

The command has no arguments or options.

HORIZON: Signed out.

hrzn tunnelCopy Anchor Link

Put a local server on a public HTTPS URL. The command stays running and prints each request. Press Ctrl+C to stop it.

hrzn tunnel <url>

Run hrzn login first. Without a sign-in, the command prints You are not signed in. Run hrzn login <account-id>. and exits with code 1.

If <url> isn't a valid URL, the command prints this and exits:

Give the local URL to expose, for example: hrzn tunnel http://localhost:3000

When the tunnel connects, the terminal prints a header, a blank line, then one line per request.

HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run
  Forwarding   http://localhost:3000
  Request log  <request-log-link>

  POST    200  /api/webhooks/stripe
  GET     200  /api/webhooks/x?crc_token=abc
  WS      101  /socket

A request line shows the method, the status your local server returned and the path with its query string. A WebSocket upgrade shows WS. The status is green for 2xx, amber for 3xx and 4xx, and red for 5xx. When your local server can't be reached, the status reads ERR.

The CLI sets the Host header to your local address. The public host arrives in X-Forwarded-Host.

Status messagesCopy Anchor Link

The first terminal exits with code 0 when another terminal takes the subdomain. It exits with code 1 when Horizon closes the tunnel for any other reason.

Environment variablesCopy Anchor Link

The CLI reads these variables from your shell and from a .env file in the folder where you run the command.

The CLI also reads other variables, but only when run from the Horizon source tree. They aren't for general use and this page leaves them out.