lenneTech/using-lt-cli

Referencia de LT CLI

Advertencias

• lt fullstack init sin --noConfirm bloquea Claude Code para siempre — Los prompts interactivos (nombre del proyecto, inicialización de git, selección de plantilla) esperan entrada por stdin. Claude Code no puede responderles, y la sesión se queda en "Unfurling..." sin consumir tokens. Pasa --noConfirm + todas las banderas requeridas (--name X --frontend nuxt --git false) cuando invoques la CLI lt desde Claude Code.
• --api-link y --frontend-link crean ENLACES SIMBÓLICOS, no copias — Los cambios en la plantilla checkout (nest-server-starter, nuxt-base-starter), donde sea que esté en esta máquina, afectan inmediatamente al proyecto enlazado. Esto es una característica para desarrollo de frameworks, pero sorprende a los desarrolladores que esperan copias. Documéntalo en el README del proyecto cuando uses --api-link.
• lt git reset es DESTRUCTIVO e irreversible — Está al lado del seguro lt git get en el menú de la CLI. reset hace git reset --hard seguido de un force-pull, destruyendo TODOS los cambios locales sin confirmación. Nunca lo ejecutes en una rama con trabajo sin subir. Prefiere git stash + lt git get.
• lt server object X --controller genera REST, NO GraphQL — Por defecto es REST. Para proyectos GraphQL, usa --resolver. La CLI no detecta automáticamente los patrones de proyecto existentes; debes especificarlo explícitamente.
• lt fullstack convert-mode reescribe el árbol fuente — Cambiar entre modo npm y vendor mueve el código del framework dentro/fuera de src/core/ (API) o app/core/ (App). La operación es reversible pero NO idempotente a mitad de ejecución: siempre haz commit antes de empezar, para que una conversión fallida se pueda revertir con git reset.
• --next es experimental e incompatible con lt server module/object/addProp/test/permissions — Cuando se usa lt server create --next o lt fullstack init --next, la API se clona desde nest-base (Bun + Prisma 7 + Postgres + Better-Auth) en lugar de nest-server-starter. Los generadores posteriores apuntan al diseño clásico de nest-server (modelos Mongoose, src/server/modules/, etc.) y no funcionarán en un proyecto nest-base. Úsalo solo para prototipado desde cero; para trabajo en producción prefiere la plantilla por defecto.
• macOS: un $TMPDIR largo rompe Nuxt SSR bajo lt dev up — En macOS, $TMPDIR es una ruta larga por usuario (/var/folders/…, a menudo >~49 caracteres). El vite-node de Nuxt 4.4.7 construye una ruta de socket Unix bajo ella que supera el límite de 104 caracteres del SO → SSR falla con un 500. Solución: inicia con un directorio tmp corto, TMPDIR=/tmp lt dev up. (En Linux $TMPDIR=/tmp es corto, así que esto solo ocurre en macOS).
• macOS: El puerto HMR WebSocket 24678 colisiona entre proyectos lt dev paralelos — Dos proyectos lt dev ejecutándose a la vez intentan enlazar al puerto HMR WS de Vite 24678. vite.server.hmr.port es ignorado por Nuxt 4.4.7, por lo que no se puede reasignar en la configuración. Esto no es fatal — la recompilación SSR sigue funcionando; solo se ven afectados los envíos live-HMR en el segundo proyecto. Recarga la página para recoger los cambios allí.

Límites del Skill

Intención del Usuario	Skill Correcto
"lt fullstack init"	ESTE SKILL
"lt git get feature-branch"	ESTE SKILL
"lt server create my-project"	ESTE SKILL
"lt server module / object / addProp"	generating-nest-servers
"lt server permissions"	generating-nest-servers
"Create a NestJS module"	generating-nest-servers
"Build a Vue component"	developing-lt-frontend
"lt deployment create"	ESTE SKILL (ver el comando lt deployment create)
"Deploy to TurboOps / go live / turbo deploy / deployment stage"	deploying-to-turboops

Después de lt fullstack init:

• Trabajo backend (projects/api/) → generating-nest-servers
• Trabajo frontend (projects/app/) → developing-lt-frontend

Comandos

lt git get — Checkout/Crear Rama

lt git get <branch-name>    # alias: lt git g

1. La rama existe localmente → cambia a ella
2. La rama existe en remoto → la checkout y trackea
3. No existe ninguna → crea nueva rama desde la actual

lt git reset — Resetear a Remoto

lt git reset

Obtiene lo último del remoto, resetea la rama actual a origin/<branch>. Destructivo — todos los cambios locales se pierden.

lt fullstack init — Crear Espacio de Trabajo Fullstack

# No interactivo
lt fullstack init --name <Name> --frontend <angular|nuxt> --git <true|false> --noConfirm \
  [--git-link <URL>] [--api-link <path>] [--frontend-link <path>] [--next]

Parámetro	Requerido	Descripción
--name	Sí	Nombre del espacio de trabajo (PascalCase)
--frontend	Sí	angular o nuxt
--git	Sí	Inicializar git: true / false
--noConfirm	No	Saltar prompts de confirmación
--git-link	No	URL del repositorio git
--api-branch	No	Rama de nest-server-starter
--frontend-branch	No	Rama del starter frontend
--api-copy / --api-link	No	Plantilla API local (copia / symlink)
--frontend-copy / --frontend-link	No	Plantilla frontend local (copia / symlink)
--next	No	Experimental — clona nest-base (Bun + Prisma 7 + Postgres + Better-Auth) para la API. Fuerza apiMode = Rest, frameworkMode = npm, y salta la instalación del espacio de trabajo (ejecuta pnpm install para app y bun install para api manualmente). Los comandos posteriores lt server module/object/addProp/test NO son compatibles con la estructura resultante.

Prioridad: --*-link > --*-copy > --*-branch > predeterminado (clon de GitHub)

Estructura creada:

<workspace>/
├── projects/
│   ├── api/    ← nest-server-starter (o nest-base con --next)
│   └── app/    ← nuxt-base-starter (o ng-base-starter)
├── package.json
└── .gitignore

Post-creación:

cd <workspace> && pnpm install
lt dev init                      # idempotente: parches ENV + registro; ejecuta automáticamente `lt dev install` primero si la máquina no está configurada aún
lt dev up                        # Inicia API + App detrás de Caddy bajo https://<slug>.localhost

# Con --next: instalar por subproyecto, sin instalación del espacio de trabajo
cd <workspace>/projects/app && pnpm install
cd <workspace>/projects/api && bun install

(Recurre a pnpm -r --parallel run start en los puertos predeterminados 3000/3001 si no se usa lt dev.)

lt dev — Orquestación de Proyectos Paralelos (Caddy + HTTPS)

Sirve cada proyecto lt bajo URLs HTTPS estables (<slug>.localhost, api.<slug>.localhost) a través de Caddy, para que múltiples proyectos puedan ejecutarse lado a lado sin colisionar en 3000/3001 y sin cruce de autenticación. Usa esto en cada lt-monorepo o proyecto independiente de API/App.

lt dev install                   # Una vez por máquina: prepara LaunchAgent/unidad systemd dedicado + stub Caddyfile + recordatorio CA
lt dev uninstall [--purge]       # Elimina el servicio lt-dev (--purge también elimina Caddyfile + logs)
lt dev init                      # Una vez por proyecto (idempotente): parches ENV + registro
lt dev up                        # Inicia API + App detrás de Caddy
lt dev down                      # Detiene procesos + elimina bloque Caddy (también desmonta cualquier stack de prueba aislado)
lt dev test                      # PRUEBAS E2E AISLADAS con Playwright: stack paralelo + BD dedicada `<slug>-test`, auto-desmontaje
lt dev test --shard              # Distribuye en 2 stacks aislados (predeterminado — punto óptimo estable)
lt dev test --shard 3            # Distribuye en N stacks aislados (cada uno con sus propios puertos/Caddy/BD `<slug>-test-<i>`)
lt dev test --shard auto         # Tamaño N basado en CPU + RAM de esta máquina (conservador)
lt dev test down                 # Desmonta el/los stack(s) de prueba aislados (sin residuos)
lt dev status                    # Muestra URLs + PIDs + estado upstream en vivo para ESTE proyecto (incl. cualquier stack de prueba)
lt dev status --all              # Lista todos los proyectos registrados + estado de ejecución
lt dev doctor                    # Diagnostica problemas de Caddy / CA / DNS / puerto
lt dev tunnel [--api]            # Cloudflare Quick Tunnel en primer plano: URL pública *.trycloudflare.com

Qué hace cada subcomando:

• install — Una vez por máquina. Verifica que caddy esté en PATH (sugiere brew install caddy si falta), crea el stub ~/.lenneTech/Caddyfile, escribe + prepara un LaunchAgent dedicado (macOS, ~/Library/LaunchAgents/tech.lenne.lt-dev-caddy.plist) o unidad systemd-user (Linux). Espera hasta 8s a que el endpoint admin de Caddy (:2019) responda, valida el archivo, y recuerda ejecutar sudo -E HOME="$HOME" caddy trust (el -E HOME="$HOME" es obligatorio — sin él sudo cambia HOME a /var/root y la instalación del CA falla silenciosamente). NO usa brew services start caddy — su plist codifica --config /opt/homebrew/etc/Caddyfile y entra en bucle de caídas contra nuestra ubicación del Caddyfile. Auto-encadenamiento: cuando se ejecuta dentro de un proyecto lt-dev no inicializado, ejecuta init después (--skip-init para optar por no participar).
• uninstall — Contraparte simétrica de install. Expulsa el LaunchAgent / unidad systemd, elimina el archivo de unidad. Con --purge también elimina ~/.lenneTech/Caddyfile y los logs de caddy. NO elimina el binario caddy en sí (usa brew uninstall caddy si lo deseas).
• init (alias migrate) — Idempotente. Construye la identidad del proyecto (slug = nombre de package.json, subdominios a partir del diseño del monorepo), parchea el antiguo port: 3000 / port: 3001 / destinos de proxy Vite / URLs de Playwright codificados a variantes conscientes del entorno (se preservan los valores por defecto), persiste en ~/.lenneTech/projects.json, inyecta un bloque "Local Development (lt dev)" en todos los archivos CLAUDE.md, añade .lt-dev/ a .gitignore. Auto-encadenamiento: ejecuta install primero cuando la máquina aún no está preparada (--skip-install para optar por no participar).
• up — Asigna puertos upstream internos (4000+, nunca 3000/3001), inserta/actualiza el bloque Caddy con reverse_proxy 127.0.0.1:<port> + recarga, exporta PORT, HOST=127.0.0.1 / NITRO_HOST=127.0.0.1 (fija servidores de desarrollo a IPv4 para que el upstream sea inequívoco), BASE_URL, APP_URL, NUXT_API_URL, NUXT_PUBLIC_API_URL, NUXT_PUBLIC_SITE_URL, NUXT_PUBLIC_STORAGE_PREFIX, NUXT_PUBLIC_API_PROXY=false, la BD de la API (MongoDB: NSC__MONGOOSE__URI; PostgreSQL / MySQL / MariaDB, desde lt CLI 1.54.0: NSC__DATABASE__URL y NSC__DATABASE__OWNER_URL solo para la API, en una base de datos propia del stack que el primer inicio crea como rol propietario, por lo que el propietario necesita CREATEDB en PostgreSQL o CREATE + GRANT OPTION en MySQL / MariaDB; registrada sin credenciales bajo dbUrls en ~/.lenneTech/projects.json), NODE_EXTRA_CA_CERTS (CA raíz de Caddy para que las peticiones SSR de Nuxt confíen en HTTPS), más alias heredados API_URL / SITE_URL para proyectos que preceden a la convención NUXT_*. Luego inicia pnpm start (api) + pnpm dev (app) en modo detached. Las comprobaciones previas se niegan a iniciar cuando Caddy falta, el demonio de Caddy está caído, hay una sesión existente activa, o los puertos internos están ocupados. Logs en <root>/.lt-dev/{api,app}.log.
• down — Envía SIGTERM al grupo de procesos guardado (PID negativo) para que los hijos (Vite, Nest watcher, etc.) también lo reciban. Elimina el bloque Caddy del proyecto + recarga. También desmonta cualquier stack de prueba aislado (lt dev test) para este proyecto.
• test — E2E AISLADAS. Levanta un SEGUNDO stack paralelo (<slug>-test.localhost / api.<slug>-test.localhost, puertos propios + bloque Caddy + puente .lt-dev/.env.test) en una BD dedicada <slug>-test (separada de la de desarrollo <slug>-local y de la API-test <slug>-e2e), ejecuta la suite de Playwright (la configuración global restablece esa BD una vez antes de la primera prueba), luego se desmonta automáticamente sin residuos. Se ejecuta junto a — y nunca toca — la sesión de desarrollo. --keep lo deja levantado; lt dev test down lo detiene; --api ejecuta las pruebas de API (ya aisladas) en su lugar; --debug = PWDEBUG+headed; -- <args> se pasa a Playwright. --shard N ejecuta la suite dividida en N stacks COMPLETAMENTE aislados en paralelo (cada uno con sus propios puertos + bloque Caddy + BD <slug>-test-<i>) + N procesos --shard=i/N de Playwright — la matriz de paridad CI local. Un --shard simple por defecto es 2 (el punto óptimo estable: N≥3 sobrecarga los núcleos de rendimiento en una máquina de desarrollo típica → resultados inestables); --shard auto dimensiona N desde CPU+RAM (conservador). Las partes locales comparten UNA máquina (a diferencia de los contenedores por parte de CI), por lo que la CLI exporta LT_DEV_TEST_SHARDS para que el playwright.config del proyecto relaje los tiempos de espera solo bajo esa carga (CI sigue siendo rápida). lt dev test down recupera todas las partes. Requiere la versión de la CLI lt que incluya esta sesión aislada.
• status / status --all — Proyecto actual: subdominios → puertos upstream, URI de BD, PIDs de sesión (vivos/muertos), estado upstream lsof en vivo. --all: cada proyecto registrado con un indicador ●/○.
• doctor — Caddy en PATH, lt-dev LaunchAgent / unidad systemd cargada, demonio ejecutándose, Caddyfile válido, puertos 80/443 libres o en manos de Caddy, *.localhost resuelve (loopback IPv4 o IPv6), estado del registro.
• tunnel — Cloudflare Quick Tunnel en primer plano: cloudflared tunnel --url https://<slug>.localhost --http-host-header <slug>.localhost --no-tls-verify. Imprime una URL pública *.trycloudflare.com (5-10s) y se ejecuta hasta Ctrl-C. Por defecto expone la App; --api cambia el destino. Las cookies de autenticación en el dominio localhost NO son válidas en la URL del túnel — añade la URL del túnel a trustedOrigins de Better-Auth para que los flujos de inicio de sesión funcionen. Inicia un segundo lt dev tunnel --api en paralelo para uso externo completo.

Sobrescribe el binario de inicio mediante LT_PNPM_BIN (por ejemplo, para proyectos basados en bun a través de un script wrapper).

lt ticket — Entornos de desarrollo paralelo por ticket

Trabaja en varios tickets/características de UN proyecto al mismo tiempo — cada uno en su PROPIO git worktree + su PROPIO stack lt dev aislado (URLs propias, puertos, bloque Caddy, BD vacía) — de modo que varios tickets se puedan probar en navegador Y con E2E en paralelo sin ninguna interferencia cruzada.

lt ticket start DEV-2200            # worktree (rama feat/DEV-2200 desde origin/dev) + pnpm install + lt dev up