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> [--domain <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 --domain is set to a custom domain you've verified for your account.

localcan https <port> [--domain <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. --domain is not supported. Requires a license. Without a license the command exits with an error (there's no .local fallback for raw TCP).

Without a license, localcan http and localcan https still work but publish only a .local URL and print the Free plan signup link. --domain 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":  "1.0.0",
  "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 tunnel rm <url>

Release a Public URL entirely. Removes the endpoint, plus the now-empty service and project when it was the last one. Pass a full URL or a bare host. With --json it returns { "url", "removed", "service_removed", "project_removed" }.

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/).

Snapshots

Publish a static copy of a folder that LocalCan serves at a Public URL while your machine is offline. These commands need a running daemon. See Snapshots for the full feature.

localcan snapshot publish <path> [--name <name>]

Publish a folder to a new Public URL. LocalCan builds the folder when it is a buildable project, or packs it as is when it already holds an index.html. Streams build and upload progress, then prints the URL and what was published (5 files · 6 KB). --name shapes the address, so --name my-app gives my-app-12.localcan.dev. With --json the result is one object on stdout.

localcan snapshot add <url> <path>

Attach a Snapshot to a Public URL that does not have one yet, so an existing link keeps serving after your machine goes offline. It stops and points you at update when the URL already has a Snapshot.

localcan snapshot update <url> [--path <path>]

Rebuild and re-publish the Snapshot on a Public URL. Pass --path to publish a different folder. It stops and points you at add when the URL has no Snapshot yet.

localcan snapshot ls

List your Snapshots. Columns: URL, SERVING (live while your tunnel is up, snapshot while it is down), MODE, FRESH (stale when a source file is newer than the Snapshot), PUBLISHED, SOURCE. With --json each row is one object.

localcan snapshot rm <url>

Remove the Snapshot from a Public URL. The URL stays reserved and keeps serving live while your tunnel is up. Release the URL itself with localcan tunnel rm.

Access control

Password-protect a Public URL so only people who have the password can open it. Protection is enforced on LocalCan's servers, so it covers the URL's Snapshot too and keeps working while your machine is offline. These commands need a running daemon and a subscription plan. See Access control for the full feature.

localcan access password <url> [--set <pw>]

Password-protect a Public URL. LocalCan generates a strong password and prints it, unless --set supplies your own. The password is stored with the project, so access show can read it back later. With --json the result is { "url", "mode", "password" }.

localcan access clear <url>

Remove protection, making the URL public again. Leaves the URL and its Snapshot in place.

localcan access show <url>

Print one Public URL's protection: the mode (public or password) and, when it is password-protected, the password.

localcan access ls

List every Public URL with its protection. Columns: URL, PROTECTION. Passwords are shown by access show, not here.

Traffic inspector

localcan traffic status | enable | disable | clear

Show capture state, turn capture on or off, or drop all captured traffic.

localcan traffic ls [--last N] [--host H] [--project P] [--method M] [--status S]

List recent captured exchanges (newest first), then exit. --status accepts 200, 2xx, 4xx, or 5xx. With --json each row is one NDJSON object.

localcan traffic get <id> [--format markdown|curl|http|har|json] [--redact]

Export one captured exchange. Raw by default, --redact strips secrets. Output is written verbatim for redirecting or piping.

localcan traffic watch [filters]

Stream new exchanges live until Ctrl-C. Same filters as ls.

See Traffic for filters and output shapes.

AI agents (MCP)

localcan mcp

Run a Model Context Protocol server over stdio so AI agents can read captured traffic and manage your Public URLs. Launched by an MCP host, not by hand.

localcan mcp status | enable | disable | redact <on|off> | access <read_only|read_write>

Manage MCP access from the terminal (the same controls as the desktop Settings). status shows agent access, redaction, and write access. enable and disable allow or block agent access. redact on|off toggles secret redaction in agent responses. access read_only|read_write allows or blocks the write tools (default read_only). Changes apply immediately.

See AI agents for setup and tools.

License

localcan license activate <key> [flags]

Activate a license key. Flags:

localcan license deactivate

Free the seat. Daemon keeps running and drops to unlicensed (.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 with or without a license.

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":     "1.0.0",
  "desktop_version": "3.0.0",
  "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
}

Without a key, mode is "unlicensed", 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": "1.0.1", "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 1.0.0 (client)
daemon   1.0.0 (running)

JSON shape:

{
  "client":        "1.0.0",
  "daemon":        "1.0.0",
  "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.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: