Reference

Full listing of every localcan command, flag, and what it returns.

Every command supports -h/--help to print a short synopsis and --json (or --output json) to emit machine-readable output instead of formatted text.

Quick tunnels

localcan http <port> [--url <custom-domain>]

Open an ephemeral HTTP tunnel to http://localhost:<port>. Auto-starts the daemon if it isn't running. Generates a random LocalCan.dev URL unless --url is set to a custom domain you've verified for your account.

localcan https <port> [--url <custom-domain>]

Same as http but for local servers that already terminate TLS. LocalCan trusts your server's certificate even if it's self-signed.

localcan tcp <port>

Open a raw TCP tunnel. --url is not supported. Requires a license. In free mode the command exits with an error (there's no .local fallback for raw TCP).

In free mode, localcan http and localcan https still work but publish only a .local URL. --url is rejected without a license.

See Quick tunnels for more.

Daemon

localcan start [-d|--detach] [-v|--verbose]

Start the daemon. Foreground by default. --detach backgrounds the process. --verbose enables debug logging.

localcan stop

Stop the running daemon.

localcan restart [-d|--detach] [-v|--verbose]

Stop the running daemon (if any) and start a fresh one. Same flags as start.

localcan reload

Tell the running daemon to re-read every project file in ~/.localcan/projects/. The right command after editing YAML by hand.

localcan status

Print daemon status: version, RPC protocol, project count, listening address. JSON shape:

{
  "status":   "running",
  "version":  "3.0.0-beta.4",
  "protocol": 1,
  "projects": 2,
  "address":  "/Users/you/.localcan/daemon.sock"
}

Resources

localcan projects ls

List loaded projects. Columns: ID, NAME, SERVICES. JSON shape:

{
  "my-app": {
    "id": "my-app",
    "file_path": "/Users/you/.localcan/projects/my-app.yml",
    "ephemeral": false,
    "project": {
      "name": "My App",
      "icon": "🚀",
      "services": { "web": { "target": "http://localhost:3000", "endpoints": [/* … */] } }
    }
  }
}

localcan services ls

List services across all projects. Columns: PROJECT, SERVICE, TARGET, ENDPOINTS. JSON shape:

[
  {
    "project_id": "my-app",
    "service_id": "web",
    "name": "Storefront",
    "target": "http://localhost:3000",
    "endpoints": 2
  }
]

localcan tunnel ls

List active tunnels (Public URLs). Columns: TUNNEL URL, TARGET, PROTOCOL, PROJECT, EDGE. JSON shape:

[
  {
    "key":          "my-app/web/0",
    "project_id":   "my-app",
    "service_id":   "web",
    "tunnel_url":   "https://swift-falcon-12.localcan.dev",
    "local_target": "http://localhost:3000",
    "protocol":     "http",
    "edge_host":    "edge-eu1.localcan.dev"
  }
]

localcan config show

Pretty-print the daemon configuration and loaded projects. Falls back to reading config.yml from disk if the daemon isn't running. JSON shape:

{
  "daemon": { "license_key": "localcan_…", "device_id": "…", "proxy_https": { "enabled": true } },
  "projects": { "my-app": { "/* same as projects ls */": "" } }
}

localcan config path

Print the data directory (~/.localcan/).

License

localcan license activate <key> [flags]

Activate a license key. Flags:

localcan license deactivate

Free the seat. Daemon keeps running and drops to free mode (.local + proxy keep serving). Public URLs and localcan tcp pause until a new key is activated.

localcan license set-usage-data <yes|no>

Enable or disable anonymous usage data. Telemetry is opt-in and off by default. Works in free mode and when activated.

localcan license status

Print the current mode, license key (masked), device, platform, CLI and desktop version, and update window. JSON shape:

{
  "mode":            "licensed",
  "licensed":        true,
  "device_id":       "c5b1…",
  "device_name":     "my-laptop",
  "license_key":     "localcan_xxxxxxxxxxxx****",
  "platform":        "darwin",
  "arch":            "arm64",
  "cli_version":     "3.0.0-beta.4",
  "desktop_version": "3.0.0-beta.4",
  "terms_version":   "2026-05-20",
  "subscription": {
    "status": "trialing"
  },
  "updates": {
    "expired":             false,
    "allowed_until":       "2027-01-01T00:00:00Z",
    "releases_behind":     [],
    "cli_releases_behind": []
  },
  "cli_update": null
}

In free mode (no key), mode is "free", licensed is false, and subscription, updates, and custom_domains are absent. terms_version is always present and is the empty string until the Terms are accepted.

subscription is present when the activated key belongs to a subscription plan.

cli_update is non-null only on standalone builds when a newer CLI is available, and carries { "name": "3.0.0-beta.5", "pub_date": "2026-05-01T12:00:00Z" }.

Other

localcan accept-terms

Record acceptance of the Terms of Service↗ non-interactively, then exit. Useful for CI and scripted installs where the first-run prompt cannot run. Engine commands (start, http, https, tcp, restart) refuse to run until the Terms are accepted, either here or at the interactive prompt.

localcan version

Print the client and daemon versions:

localcan 3.0.0-beta.4 (client)
daemon   3.0.0-beta.4 (running)

JSON shape:

{
  "client":        "3.0.0-beta.4",
  "daemon":        "3.0.0-beta.4",
  "daemon_status": "running"
}

daemon_status is "running", "not running", or "unknown". When the daemon is not running, daemon is an empty string.

localcan update [--check]

Download and replace the binary in place. --check only reports whether an update is available. No-op on bundled installs (the desktop app's auto-updater handles this).

localcan install-cli [--check|--uninstall]

Unix only. Symlinks the running binary into ~/.localcan/bin/localcan and adds that directory to your shell's PATH by appending a guarded block to your zsh, bash, or fish rc files. Normally invoked automatically — by the desktop app on macOS, by install-beta.sh on Linux — so you rarely run it by hand. Cases where you might: re-running after switching shells, uninstalling PATH wiring (--uninstall), or inspecting the current state (--check, prints JSON).

Global flags

These can appear anywhere in the argument list: