Installing @myrialabs/tunnelkit globally exposes a tunnelkit command that drives the same three tunnel modes
as the library — from your terminal, no code.
bun add -g @myrialabs/tunnelkit
# or: npm i -g @myrialabs/tunnelkitThe CLI needs the cloudflared binary. It is downloaded automatically into ~/.tunnelkit/bin on
first use; you can also run tunnelkit install ahead of time, or rely on a cloudflared already
on your PATH.
tunnelkit <command> [options]Commands are grouped by mode. Authentication is under local because only named tunnels touch your
Cloudflare account — quick needs nothing and remote runs from a token.
Run tunnelkit with no command in a terminal to open a live control panel — a persistent
view of every running tunnel, updating in place. Piped or in CI the bare command prints help
instead, so scripts are unaffected.
tunnelkit # control panel (in a TTY)The panel shows each tunnel's status, public URL or ingress routes, and only the actions that apply to the current selection:
tunnelkit > tunnels
❯ ● quick-3000 → https://aaa.trycloudflare.com
● prod → 2 routes
- http://localhost:3000 → app.example.com
- http://localhost:8080 → api.example.com
● my-app → 2 routes
- http://localhost:4000 → shop.example.com
- http://localhost:4001 → cms.example.com
[↑/↓] select [n] new tunnel [x] stop [c] copy URL [m] manage saved [q] quit
| Key | Action |
|---|---|
↑/↓ (or j/k) |
Move the selection |
n |
Start another tunnel — opens a mode wizard (Quick / Remote / Local / a saved one) |
x |
Stop the selected tunnel; the others keep running |
c |
Copy the selected tunnel's URL to the clipboard |
m |
Manage saved tunnels (edit tokens/routes, forget entries, or log out from Cloudflare) |
q / Ctrl+C |
Stop all tunnels and exit |
Pressing n opens a breadcrumbed wizard (mode → prompts for port / token / routes). Esc steps
back one level while filling forms instead of jumping out of the flow. Long-running steps keep their
progress visible under the breadcrumb:
tunnelkit > new tunnel > local
✓ tunnel id 7ae239c2-...
✓ app.example.com routed
✓ api.example.com routed
⠋ Starting local tunnel... (Esc to cancel)
With no tunnels running the wizard opens automatically. Starting a tunnel by command (e.g.
tunnelkit quick 3000) opens the panel automatically, so you can add more from there.
Outside a TTY, commands run non-interactively — missing arguments error, destructive actions skip
confirmation, and there is no panel. Pass --yes to suppress confirmation
prompts in a TTY.
Start a quick TryCloudflare
tunnel to a local service. Prints the public URL, then opens the control panel
in a terminal; otherwise runs in the foreground until Ctrl+C. No Cloudflare account required.
tunnelkit quick <port|url> [--auto-stop <minutes>]| Option | Default | Description |
|---|---|---|
<port|url> |
— | What to expose (required). A bare port is shorthand for http://localhost:<port>; a full URL is used as-is. |
--auto-stop <minutes> |
0 |
Minutes until auto-stop; 0 means run until stopped. |
tunnelkit quick 3000
tunnelkit quick http://localhost:8080 --auto-stop 30
tunnelkit quick https://127.0.0.1:8443Run a dashboard-managed (token-based) tunnel. Ingress is configured in the Cloudflare Zero Trust
dashboard and pushed to cloudflared at runtime — hostnames are printed as they arrive. Opens the
panel in a terminal; otherwise runs in the foreground until Ctrl+C.
tunnelkit remote run [name] [--token <token>] [--name <name>] [--id <id>]| Option | Default | Description |
|---|---|---|
[name] |
— | A saved tunnel to reuse; its stored token is loaded automatically. |
--token <token> |
$CF_TUNNEL_TOKEN |
Tunnel token; falls back to the env var. |
--name <name> |
the name or id | Name used to save & reuse the token. |
--id <id> |
cli-remote |
Stable identifier for the running tunnel. |
Supply the token once, then reuse it by name:
tunnelkit remote run --token "$CF_TUNNEL_TOKEN" --name prod # first time — saves as "prod"
tunnelkit remote run prod # subsequent runsPass --no-save to run without reading or writing the store.
Local tunnels are the only mode that talks to your Cloudflare account, so authentication, listing,
and deleting all live under local.
local login authenticates with Cloudflare for named tunnels. It prints an authorization URL —
open it in a browser and approve. The origin certificate is saved under ~/.tunnelkit.
local logout removes that certificate.
tunnelkit local login
tunnelkit local logoutCreate a named tunnel, route one or more hostnames to it, and run it — the full local lifecycle in
one command. Requires authentication with tunnelkit local login.
Opens the panel in a terminal; otherwise runs in the foreground until Ctrl+C.
tunnelkit local run <name> --route <hostname=service> [--route …]
tunnelkit local run <name> --hostname <host> --service <url>| Option | Description |
|---|---|
<name> |
Name for the tunnel (required). |
--route <hostname=service> |
Ingress rule, repeatable. e.g. app.example.com=http://localhost:3000. |
--hostname <host> |
Single ingress hostname (pair with --service). |
--service <url> |
Local service for --hostname. |
tunnelkit local run my-app --route app.example.com=http://localhost:3000
tunnelkit local run my-app \
--route app.example.com=http://localhost:3000 \
--route api.example.com=http://localhost:4000
tunnelkit local run my-app # reuse the saved tunnel and routesThe tunnel and its routes are saved by default. Pass --no-save to skip saving (and to ignore any
previously saved tunnel of the same name). If a tunnel with the same name already exists on
Cloudflare but isn't in use, it is treated as an orphan and recreated.
List every named tunnel on the authenticated account, with its id and active connection count.
tunnelkit local listDelete a named tunnel by name or id. Prompts for confirmation in a terminal (skip with --yes).
Also drops any locally-saved entry for that tunnel.
tunnelkit local delete my-app
tunnelkit local delete 6d8e…-uuidsaved lists tunnels saved locally for reuse — remote tokens and local tunnel configs. forget
removes a single entry by name. Remote tokens are dashboard-managed, so forgetting one only drops
the local copy of the token. For local tunnels, forget also DELETES the tunnel from
Cloudflare (irreversible) — it requires Cloudflare auth, confirms in a terminal, and --yes
skips the confirm.
tunnelkit saved # list all saved remote + local tunnels
tunnelkit forget prod # remote: drop the saved token
tunnelkit forget storefront # local: drop the local entry + delete from Cloudflare
tunnelkit forget prod --yes # skip the confirmation promptUse --no-save on any run to skip the store entirely.
Print a shortcut link to the Cloudflare Zero Trust Tunnels dashboard — the ?to=/:account/…
form resolves the signed-in account, so no account id is needed.
tunnelkit dashboardDownload the cloudflared binary into ~/.tunnelkit/bin (or --install-dir).
tunnelkit install # latest
tunnelkit install 2024.12.2 # pin a releaseShow whether cloudflared is available, its version, and its resolved path.
tunnelkit statusCheck the npm registry for a newer version of @myrialabs/tunnelkit. If one is found, it auto-detects your package manager (npm, bun, yarn, pnpm) and runs the update.
tunnelkit updateThe interactive control panel also shows a best-effort update hint (silent on failure) when starting a session.
tunnelkit version # or -v
tunnelkit help # or -hWith no command, tunnelkit opens the control panel in a terminal, or prints
help when not in a TTY.
These apply to every command.
| Option | Description |
|---|---|
--yes, -y |
Skip confirmation prompts (e.g. local delete). Also skipped automatically without a TTY. |
--no-save |
Don't read or write the saved-config store for this run. Applies to remote run and local run. |
--data-dir <dir> |
Override the data directory (cert.pem, credentials, configs, saved store). Default ~/.tunnelkit. |
--install-dir <dir> |
Override the managed binary directory. Default ~/.tunnelkit/bin. |
--verbose |
Print library diagnostics to stderr. |
-h, --help |
Show help. |
-v, --version |
Show the version. |
-- ends option parsing; everything after it is treated as a positional argument.
| Code | Meaning |
|---|---|
0 |
Success (or a foreground tunnel was stopped with Ctrl+C / q). |
1 |
An error occurred — invalid arguments, a missing binary, or a failed Cloudflare operation. Details are printed to stderr. |
130 |
An interactive prompt or menu was cancelled (Esc / Ctrl+C). |