Documentation
NPM CLI

Node.js / npm — mekong-cli

mekong-cli is the official npm package for MekongTunnel. It provides:

  • A mekong-cli binary that wraps your dev server and tunnel in one command
  • A JavaScript / TypeScript SDK (require('mekong-cli/sdk')) for programmatic use
  • Auth helpers that read your saved login token automatically

npm: npmjs.com/package/mekong-cli (opens in a new tab)

Installation

# Global (makes mekong-cli available everywhere)
npm install -g mekong-cli
 
# Per-project
npm install --save-dev mekong-cli
yarn add -D mekong-cli
pnpm add -D mekong-cli

The mekong binary (Go) is required separately. See Installation.

Quick start — CLI

# Tunnel an already-running server on port 3000
mekong-cli 3000
 
# Start dev server + tunnel together
mekong-cli --with "next dev" --port 3000
mekong-cli --with "vite"     --port 5173
 
# With reserved subdomain (after mekong login)
mekong-cli 3000
# → https://myapp.mekongtunnel.dev   (same URL every time)
 
# Or pass token explicitly
mekong-cli --token mkt_xxx 3000
 
# Via env var
MEKONG_TOKEN=mkt_xxx mekong-cli 3000

CLI options

OptionDescription
--with "<cmd>"Shell command to start the dev server before tunneling
--port <n> / -p <n>Local port (auto-detected from package.json if omitted)
--token <tok>API token for reserved subdomain (env: MEKONG_TOKEN)
--expire <val>Tunnel lifetime — e.g. 2h, 1d, 1w
--daemon / -dRun tunnel in background
--no-qrSuppress QR code output
--mekong <path>Custom path to the mekong binary

Token resolution order: --token flag → MEKONG_TOKEN env → ~/.mekong/config.json (written by mekong login).

mekong-cli init

Auto-detect your framework and inject a dev:tunnel script into package.json:

mekong-cli init
{
  "scripts": {
    "dev":        "next dev",
    "dev:tunnel": "mekong-cli --with \"next dev\" --port 3000"
  }
}

Then just run:

npm run dev:tunnel

JavaScript / TypeScript SDK

Use the SDK to control tunnels programmatically — great for test setups, integration tests, or custom tooling.

const mekong = require('mekong-cli/sdk')
// ESM / TypeScript:
// import mekong from 'mekong-cli/sdk'

expose(port, opts?) → Promise<{ url, stop }>

Start a tunnel and get the public URL:

const { url, stop } = await mekong.expose(3000)
console.log('Public:', url)   // https://myapp.mekongtunnel.dev
 
// Stop when done
stop()

With options:

const { url, stop } = await mekong.expose(3000, {
  token:  'mkt_xxx',   // override saved token
  expire: '2h',
  noQr:   true,        // suppresses QR (default true in SDK mode)
})

Token resolution: opts.token → MEKONG_TOKEN env → ~/.mekong/config.json.

login() → Promise<string>

Authenticate via the browser device flow — same as mekong login in the terminal:

const token = await mekong.login()
// Opens mekongtunnel.dev/cli-auth in the browser,
// polls until you approve, then saves ~/.mekong/config.json.
console.log('Token:', token)

logout()

Remove saved credentials:

mekong.logout()

whoami() → object | null

Return saved auth config:

const info = mekong.whoami()
// { token: 'mkt_xxx', email: 'you@example.com' }  or  null

getToken() → string | null

Read the token from env or saved config without starting anything:

const token = mekong.getToken()

Vitest / Jest integration example

import { beforeAll, afterAll, describe, it, expect } from 'vitest'
const mekong = require('mekong-cli/sdk')
 
let tunnel: { url: string; stop: () => void }
 
beforeAll(async () => {
  tunnel = await mekong.expose(3000)
  process.env.PUBLIC_URL = tunnel.url
})
 
afterAll(() => tunnel?.stop())
 
describe('public tunnel', () => {
  it('returns 200 from the public URL', async () => {
    const res = await fetch(process.env.PUBLIC_URL!)
    expect(res.status).toBe(200)
  })
})

package.json scripts examples

{
  "scripts": {
    "dev":             "next dev",
    "dev:tunnel":      "mekong-cli --with \"next dev\" --port 3000",
    "dev:tunnel:bg":   "mekong-cli --with \"next dev\" --port 3000 --daemon",
    "preview:tunnel":  "mekong-cli 3000"
  }
}

Framework guides

FrameworkPortGuide
Next.js3000Next.js
Vite5173Vite
Nuxt3000Nuxt
Remix5173Remix
SvelteKit5173SvelteKit
Astro4321Astro
Express / Fastify3000Express / Fastify

Version

Current version: v2.0.0 — npmjs.com/package/mekong-cli (opens in a new tab)

Requirements

CLI ReferenceVS Code Extension