> Complete reference for the Localport CLI — flags, protocols, environment variables, and output modes.

# CLI

The `localport` command creates a tunnel from your computer to a public URL. One command shares your dev server, game server, database, or homelab service with anything that can open a URL.

## Your first tunnel

```bash
localport http 3000 --token YOUR_TOKEN
```

Localport connects, registers the tunnel, and shows the public URL. Copy it from the status panel and share it — open it in a browser, paste it into a webhook setting, or send it to a teammate.

Tokens come from the [Localport dashboard](https://dashboard.localport.io). To avoid passing `--token` every run, [export it](#environment-variables) in your shell.

## Supported protocols

The first argument after `localport` is the protocol your local service speaks; the second is its port.

| Protocol | Use it for |
|---|---|
| `http` | Web apps and APIs — Next.js, Django, Rails, Flask, Express, anything serving HTTP. Also accepts `https` as an alias. |
| `tcp` | Game servers, databases, SSH, MQTT, gRPC, and anything else over raw TCP. |
| `tls` | TLS pass-through. Use this when your local service handles TLS itself and the bytes should reach it encrypted end-to-end. |

## Forwarding to a different machine

`localport http 3000` is shorthand for `localhost:3000`. To forward to a service on another machine — a Raspberry Pi, a container, a NAS, a coworker's laptop — point `--local` at it directly:

```bash
# Postgres on a LAN server
localport --token YOUR_TOKEN --local tcp://192.168.1.50:5432

# A web app in a Docker container
localport --token YOUR_TOKEN --local http://app.local:8080
```

The scheme on `--local` sets the protocol. Use `tcp://`, `http://`, or `tls://` to match the service.

## Flags

Short aliases sit next to the long form — `--token` and `-t` are interchangeable.

| Flag | What it does |
|---|---|
| `--token`, `-t` | Tunnel authentication token from the [dashboard](https://dashboard.localport.io). |
| `--local`, `-l` | Local address to forward to, with an optional scheme prefix (`tcp://192.168.1.50:5432`, `http://app.local:8080`). Skip when forwarding to your own machine — use the positional `<proto> <port>` form. |
| `--region`, `-r` | Edge region: `eu`, `us`, or `ap`. Omit to use Localport's default endpoint. |
| `--name` | Label for this connection. Used by mesh and shared tunnels to identify the device — see [Mesh Tunnels](/docs/mesh-tunnels). |
| `--proto` | Sets the protocol when `--local` has no scheme. Rarely needed. |
| `--noui` | Disables the live status panel and writes plain log lines instead. Auto-enabled when stdout is not a terminal. |
| `--config` | Path to a YAML configuration file — see [running several tunnels at once](#running-several-tunnels-at-once). |
| `-version` | Print version and exit. |

### Output modes

The CLI renders a **live status panel** by default: tunnel state, the public URL, region, and a table of active connections with bytes in and out.

With `--noui` — or whenever stdout is piped to a file or running under `journald` / CI — the CLI switches to **plain mode**. Every event is one timestamped line: startup, state changes, the public URL on connect, each connection opened (`conn.open`) and closed (`conn.close`) with originating IP, bytes in/out, and duration. While a tunnel has active traffic, a one-line `usage` summary is emitted every 60 seconds.

## Environment variables

```bash
export LOCALPORT_TOKEN=tok_abc123
localport http 3000
```

| Variable | What it does |
|---|---|
| `LOCALPORT_TOKEN` | Stand-in for `--token`. The flag wins if both are set. |
| `NO_COLOR` | Disable colored output. |
| `COLORTERM` | Set to `truecolor` or `24bit` for 24-bit color in the status panel. |
| `TERM` | Set to `dumb` to force plain output regardless of TTY detection. |

## Examples

```bash
# Share a web app you're building
localport http 3000 --token tok_abc123

# Host a Minecraft server
localport tcp 25565 --token tok_abc123

# Expose a Postgres database to a remote teammate
localport tcp 5432 --token tok_abc123

# Reach Home Assistant from outside your network
localport http 8123 --token tok_abc123

# Forward to a service on another box on your LAN
localport --token tok_abc123 --local http://192.168.1.20:8080

# Pin the connection to Europe
localport http 3000 --token tok_abc123 --region eu

# Name this device in a mesh tunnel
localport http 8080 --token tok_abc123 --name kitchen-pi

# Plain log output (useful in CI or systemd units)
localport http 3000 --token tok_abc123 --noui
```

## Running several tunnels at once

For a web app, a database, and a homelab service running side by side, define them in a YAML file and start everything with one command:

```bash
localport --config localport.yaml
```

Same flags, written down once. See [Configuration](/docs/configuration) for the format and worked examples.

## Reconnection and limits

- Network drops, sleeping laptops, and brief outages reconnect automatically. The public URL stays the same.
- When a bandwidth or connection limit is reached, the CLI prints which limit was hit and exits cleanly. No silent failures.

## Next steps

- [HTTP & HTTPS Tunnels](/docs/http-tunnels) — Sharing web apps and APIs
- [TCP Tunnels](/docs/tcp-tunnels) — Game servers, databases, SSH
- [Configuration](/docs/configuration) — Multi-tunnel YAML reference