Skip to content
Documentation

CLI guide

The Localians CLI

One command turns a local port into a preview link. Everything else is optional.
Beta: the localians package isn't published to npm yet, so npx localians won't resolve until it is. Install it from a Localians checkout as shown below. The commands are the same in Windows PowerShell, macOS and Linux unless noted.

Install (beta)

From the Localians repository, with Node.js 20 or newer:

Windows PowerShell
$ npm install; npm run tunnel:build$ cd tunnel\cli; npm link
macOS / Linux
$ npm install && npm run tunnel:build$ cd tunnel/cli && npm link

The build remembers which Localians server it belongs to (LOCALIANS_DEFAULT_API_URL, or the checkout's own web app), so no flags are needed. To use another server, add --api-url <url> once; the CLI remembers it after you sign in. Remove the command with npm unlink -g localians.

localians share <port>

Shares the app running on localhost:<port>. Run it in your project folder, in a second terminal next to your dev server.

$ localians share 5173
  1. Checks that something is running on that port on your computer.
  2. If this computer isn't signed in yet (or its login expired), opens your browser to approve it, then carries on.
  3. Picks the project that uses this port. If there isn't one, it asks: create a project named after your app, or use an existing one.
  4. Prints your preview link, the workspace and whether the link is public or password protected, and keeps it online until you stop.

Port selection: use the port your dev server prints (Next.js usually 3000, Vite 5173, Angular 4200). Any port from 1 to 65535 works. The CLI only ever forwards to your own computer (127.0.0.1 / ::1).

From the dashboard: the Share App page builds a command like localians share 5173 --setup k7m2xq9p4tzw. The one-time code carries the project and access (public or password) you chose there, so the CLI asks nothing. It works once, within 30 minutes, and only for your own login.

Project selection: pass --project <name-or-id> to choose one explicitly. In scripts (no interactive terminal), add --yes to allow creating a project automatically.

$ localians share 5173 --project client-dashboard
  • --host-header preserve — send the preview host to your app instead of localhost:<port>.
  • -v, --verbose — print each request and WebSocket.
  • --no-browser — print the sign-in link instead of opening a browser.

Stopping sharing

Press Ctrl+C in the terminal that's sharing, or click Stop Sharing in the dashboard. Either way the link stops working right away. A stopped link is never reused — sharing again gives you a new link.

localians login

Signs this computer in without sharing anything. share does this for you when needed, so you rarely need it. You approve the computer in your browser; the CLI gets its own access token (never your dashboard session), valid for 90 days and revocable any time in Settings → CLI. If you belong to more than one workspace, the approval page asks which one this computer may share into.

$ localians login

localians status

Shows who you're signed in as, and each preview being shared from this computer: project, local address, preview link, status and uptime.

$ localians status

localians logout

Revokes this computer's access on the server and deletes it locally. Anything this computer is sharing stops.

$ localians logout

Managing previews in the dashboard

Live Previews lists everything you're sharing with Copy Link, Open Preview and Stop Sharing, and updates as previews connect, drop and reconnect. Request and bandwidth numbers count HTTP requests and WebSocket connections forwarded to your app, and body plus WebSocket data in both directions (headers and encryption overhead aren't counted).

Local development gateway certificates

When the Localians server itself runs on your machine (contributors and beta testers), its gateway uses certificates from a local development CA (npm run tunnel:certs). Trust that CA instead of clicking through warnings, and remove it when you finish. Production previews use publicly trusted certificates and need none of this.

CLI — Windows PowerShell
$ $env:NODE_EXTRA_CA_CERTS = "C:\path\to\localians\.localians-dev\certs\ca.crt"
CLI — macOS / Linux
$ export NODE_EXTRA_CA_CERTS=~/path/to/localians/.localians-dev/certs/ca.crt
Browsers — Windows PowerShell
$ Import-Certificate -FilePath .localians-dev\certs\ca.crt -CertStoreLocation Cert:\CurrentUser\Root
Browsers — macOS
$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain .localians-dev/certs/ca.crt
Browsers — Linux (system, then Chrome/Firefox)
$ sudo cp .localians-dev/certs/ca.crt /usr/local/share/ca-certificates/localians-dev.crt && sudo update-ca-certificates$ certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "Localians dev CA" -i .localians-dev/certs/ca.crt

More help: framework guides, troubleshooting and security.