ngrok-qr-cli

CLI para exponer tu servidor local con ngrok y mostrar la URL pública como código QR en la terminal.

Requisito: Necesitas un authtoken de ngrok (gratuito). ¿Cómo obtenerlo?

Instalación global (recomendado)

npm install -g ngrok-qr-cli

Una vez instalado, ejecuta:

ngrok-qr-cli --port 3000

• -p / --port: Puerto local a exponer (por defecto: 3000)

Primeros pasos

1. Configurar el authtoken de ngrok

Crea una cuenta gratuita en ngrok.com, obtén tu token desde el dashboard y ejecútalo una vez:

ngrok-qr-cli   # la primera vez te pedirá el token interactivamente

O bien configúralo manualmente con el CLI de ngrok:

npx ngrok authtoken TU_TOKEN

El token se guarda en ~/.config/ngrok/ngrok.yml y no necesitas repetirlo.

Uso

# Puerto por defecto (3000)
ngrok-qr-cli

# Puerto personalizado
ngrok-qr-cli --port 8080
ngrok-qr-cli -p 8080

Desarrollo local

Requisitos: Node.js ≥ 18, pnpm

git clone https://github.com/tuusuario/ngrok-qr-cli.git
cd ngrok-qr-cli
pnpm install
pnpm start -- --port 3000

Scripts disponibles

| Comando | Descripción | |---------|-------------| | pnpm start | Ejecuta sin compilar (tsx) | | pnpm run dev | Modo watch (recarga automática) | | pnpm run build | Compila TypeScript → dist/ | | pnpm run lint | Linting con oxlint | | pnpm run format | Formatea el código con Prettier |

Publicar en npm

# Compilar y empaquetar
pnpm run build
pnpm pack           # genera ngrok-qr-cli-x.x.x.tgz

# Publicar al registro de npm
pnpm publish

Requiere cuenta en npmjs.com y npm login.

Instalar desde tarball (sin npm registry)

Para distribuir sin publicar en npm:

# En la máquina de desarrollo
pnpm run build
pnpm pack

# Transferir ngrok-qr-cli-2.0.0.tgz a la otra máquina y ejecutar:
npm install -g ngrok-qr-cli-2.0.0.tgz

Tecnologías

• TypeScript — lenguaje tipado
• tsup — bundler / compilador
• ngrok — túneles seguros
• qrcode — generación de QR
• chalk — estilos en terminal

Solución de problemas

"invalid tunnel configuration" / "tunnel already exists" El binario ngrok v3 tiene un bug de timing al arrancar. Esta herramienta lo resuelve automáticamente con un reintento tras detectar la sesión activa.

"Your account is limited to 1 simultaneous ngrok agent sessions" (ERR_NGROK_108) Asegúrate de que no haya otra sesión de ngrok activa. Las cuentas gratuitas permiten solo 1 agente a la vez.

El binario de ngrok no se descargó (usuarios pnpm) Ejecuta pnpm approve-builds para permitir los scripts de instalación del paquete ngrok.

Licencia

ISC