Port Buddy

CLI Reference

Every argument the portbuddy binary accepts, with the modes each option applies to.

Synopsis

portbuddy [options] [mode] [host:][port]

Options may appear before or after the positional arguments. Long options also accept an equals sign, as in --domain=my-app.

Modes

The mode is optional and defaults to http, so portbuddy 3000 and portbuddy http 3000 are the same command.

  • http — a public HTTPS URL for a local web app. See HTTP tunnels.
  • tcp — a public host and port for a raw TCP service. See TCP tunnels.
  • udp — the same, for UDP. See UDP tunnels.

Target

The target says what to expose. A bare port is the common case; the host defaults to localhost and the scheme to http.

portbuddy 3000                    # localhost:3000 over http
portbuddy 192.168.1.10:8080       # another machine on your network
portbuddy https://localhost:8443  # local server that already speaks TLS

Only http and https schemes are accepted, and the port must be in the range 1–65535.

Options

Port Buddy CLI options, the modes they apply to, and what they do
OptionModesDescription
-d, --domain <domain>HTTPUse a subdomain your account already owns, given as a label (my-app) or in full (my-app.portbuddy.dev), instead of letting the server choose.
-pr, --port-reservation <reservation>TCP, UDPPin the public address to one of your port reservations, named by its name, its port, or its full host:port.
-pc, --passcode <passcode>HTTPProtect the tunnel with a passcode for as long as it is open.
-n, --no-request-logAllDisable the live request log in the terminal.
-v, --verboseAllVerbose logging, useful when a tunnel will not connect.
-h, --helpAllPrint the usage message and exit.
-V, --versionAllPrint the CLI version and exit.

An option that does not apply to the mode you chose is ignored: --domain and --passcode are only sent for HTTP tunnels, and --port-reservation only for TCP and UDP.

Commands

There is one subcommand. It stores an API token on this machine so later tunnel commands authenticate themselves — see authentication.

portbuddy init <apiToken>

Exit codes

  • 0 — the command completed, or the tunnel was closed normally.
  • 1 — the tunnel could not be established: authentication, quota or network failure.
  • 2 — the arguments were wrong; the usage message is printed.

Examples

portbuddy init YOUR_API_TOKEN            # once per machine
portbuddy 3000                           # expose a local web app
portbuddy --domain=my-app 8080           # use a subdomain you own
portbuddy -pc my-secret 3000             # require a passcode
portbuddy tcp 5432                       # expose PostgreSQL
portbuddy tcp 5432 -pr staging-db        # pin a reserved public port
portbuddy udp 19132                      # expose a game server