lenneTech/using-lt-cli

Referência da CLI LT

Atenções (Gotchas)

• lt fullstack init sem --noConfirm bloqueia o Claude Code para sempre — Os prompts interativos (nome do projeto, init git, seleção de template) aguardam entrada do stdin. O Claude Code não pode respondê-los, e a sessão trava em "Unfurling..." sem consumo de token. Passe --noConfirm + todas as flags necessárias (--name X --frontend nuxt --git false) ao chamar a CLI lt do Claude Code.
• --api-link e --frontend-link criam SYMLINKS, não cópias — Alterações no template de checkout (nest-server-starter, nuxt-base-starter), onde quer que estejam nesta máquina, afetam imediatamente o projeto vinculado. Isso é um recurso para desenvolvimento de framework, mas surpreende desenvolvedores que esperam cópias. Documente no README do projeto ao usar --api-link.
• lt git reset é DESTRUTIVO e irreversível — Fica ao lado do seguro lt git get no menu da CLI. reset faz git reset --hard seguido de force-pull, destruindo TODAS as alterações locais sem confirmação. Nunca execute em um branch com trabalho não enviado. Prefira git stash + lt git get.
• lt server object X --controller gera REST, NÃO GraphQL — O padrão é REST. Para projetos GraphQL, use --resolver. A CLI não detecta automaticamente os padrões de projeto existentes — você deve especificar explicitamente.
• lt fullstack convert-mode reescreve a árvore de origem — Alternar entre os modos npm e vendor move o código do framework para dentro ou para fora de src/core/ (API) ou app/core/ (App). A operação é reversível, mas NÃO é idempotente durante a execução — sempre faça commit antes de começar, para que uma conversão com falha possa ser revertida via git reset.
• --next é experimental e incompatível com lt server module/object/addProp/test/permissions — Quando lt server create --next ou lt fullstack init --next é usado, a API é clonada do nest-base (Bun + Prisma 7 + Postgres + Better-Auth) em vez de nest-server-starter. Os geradores downstream visam o layout clássico do nest-server (modelos Mongoose, src/server/modules/, etc.) e não funcionarão em um projeto nest-base. Use para prototipagem greenfield apenas; para trabalho em produção, prefira o template padrão.
• macOS: um $TMPDIR longo quebra o Nuxt SSR com lt dev up — No macOS, $TMPDIR é um caminho longo por usuário (/var/folders/…, muitas vezes >~49 caracteres). O vite-node do Nuxt 4.4.7 constrói um caminho de socket Unix nele que excede o limite de 104 caracteres do SO → o SSR falha com um erro 500. Solução alternativa: inicie com um tmp dir curto, TMPDIR=/tmp lt dev up. (Linux $TMPDIR=/tmp é curto, então isso só afeta no macOS.)
• macOS: a porta HMR WebSocket 24678 colide entre projetos lt dev paralelos — Dois projetos lt dev em execução ao mesmo tempo tentam vincular a porta HMR WS 24678 do Vite. vite.server.hmr.port é ignorado pelo Nuxt 4.4.7, então você não pode reatribuí-lo na configuração. Isso não é fatal — a recompilação SSR ainda funciona; apenas os pushes de HMR ao vivo no segundo projeto são afetados. Recarregue a página para capturar as alterações lá.

Limites do Skill

Intenção do Usuário	Skill Correto
"lt fullstack init"	ESTE SKILL
"lt git get feature-branch"	ESTE SKILL
"lt server create meu-projeto"	ESTE SKILL
"lt server module / object / addProp"	generating-nest-servers
"lt server permissions"	generating-nest-servers
"Criar um módulo NestJS"	generating-nest-servers
"Construir um componente Vue"	developing-lt-frontend
"lt deployment create"	ESTE SKILL (veja o comando lt deployment create)
"Implantar no TurboOps / entrar no ar / turbo deploy / stage de implantação"	deploying-to-turboops

Após lt fullstack init:

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

Comandos

lt git get — Checkout/Criar Branch

lt git get <nome-do-branch>    # alias: lt git g

1. Branch existe localmente → muda para ele
2. Branch existe no remoto → faz checkout e rastreia
3. Nenhum existe → cria novo branch a partir do atual

lt git reset — Redefinir para o Remoto

lt git reset

Busca o mais recente do remoto, redefine o branch atual para origin/<branch>. Destrutivo — todas as alterações locais são perdidas.

lt fullstack init — Criar Workspace Fullstack

# Não interativo
lt fullstack init --name <Nome> --frontend <angular|nuxt> --git <true|false> --noConfirm \
  [--git-link <URL>] [--api-link <caminho>] [--frontend-link <caminho>] [--next]

Parâmetro	Obrigatório	Descrição
--name	Sim	Nome do workspace (PascalCase)
--frontend	Sim	angular ou nuxt
--git	Sim	Inicializar git: true / false
--noConfirm	Não	Pular prompts de confirmação
--git-link	Não	URL do repositório Git
--api-branch	Não	Branch do nest-server-starter
--frontend-branch	Não	Branch do starter frontend
--api-copy / --api-link	Não	Template de API local (cópia / symlink)
--frontend-copy / --frontend-link	Não	Template frontend local (cópia / symlink)
--next	Não	Experimental — clona nest-base (Bun + Prisma 7 + Postgres + Better-Auth) para a API. Força apiMode = Rest, frameworkMode = npm e pula a instalação do workspace (execute pnpm install para o app e bun install para a api manualmente). Os geradores downstream lt server module/object/addProp/test NÃO são compatíveis com o layout resultante.

Prioridade: --*-link > --*-copy > --*-branch > padrão (clone do GitHub)

Estrutura criada:

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

Pós-criação:

cd <workspace> && pnpm install
lt dev init                      # idempotente: patches ENV + registro; executa automaticamente `lt dev install` primeiro se a máquina ainda não estiver configurada
lt dev up                        # Inicia API + App atrás do Caddy em https://<slug>.local host

# Com --next: instalar por subprojeto, sem instalação do workspace
cd <workspace>/projects/app && pnpm install
cd <workspace>/projects/api && bun install

(Recai para pnpm -r --parallel run start nas portas padrão 3000/3001 se lt dev não for usado.)

lt dev — Orquestração de Projetos Paralelos (Caddy + HTTPS)

Serve cada projeto lt sob URLs HTTPS estáveis (<slug>.localhost, api.<slug>.localhost) via Caddy, para que vários projetos possam ser executados lado a lado sem colidir nas portas 3000/3001 e sem fiação cruzada de autenticação. Use isso em todo lt-monorepo ou projeto API/App independente.

lt dev install                   # Uma vez por máquina: inicializa unidade LaunchAgent/systemd dedicada + stub Caddyfile + lembrete CA
lt dev uninstall [--purge]       # Remove o serviço lt-dev (--purge também remove Caddyfile + logs)
lt dev init                      # Uma vez por projeto (idempotente): patches ENV + registro
lt dev up                        # Inicia API + App atrás do Caddy
lt dev down                      # Para processos + remove bloco Caddy (também derruba qualquer stack de teste isolada)
lt dev test                      # E2E ISOLADO com Playwright: stack paralela + DB `<slug>-test` dedicado, auto-teardown
lt dev test --shard              # Fragmentar em 2 stacks isoladas (padrão — ponto ideal estável)
lt dev test --shard 3            # Fragmentar em N stacks isoladas (cada uma com suas próprias portas/Caddy/DB `<slug>-test-<i>`)
lt dev test --shard auto         # Tamanho N baseado na CPU + RAM desta máquina (conservador)
lt dev test down                 # Derruba a(s) stack(s) de teste isolada(s) (sem resíduos)
lt dev status                    # Mostra URLs + PIDs + estado upstream ativo para ESTE projeto (incl. qualquer stack de teste)
lt dev status --all              # Lista todos os projetos registrados + estado de execução
lt dev doctor                    # Diagnostica problemas de Caddy / CA / DNS / porta
lt dev tunnel [--api]            # Tunnel Cloudflare Quick em primeiro plano: URL pública *.trycloudflare.com

O que cada subcomando faz:

• install — Uma vez por máquina. Verifica se caddy está no PATH (sugere brew install caddy se estiver faltando), cria o stub ~/.lenneTech/Caddyfile, escreve + inicializa um LaunchAgent dedicado (macOS, ~/Library/LaunchAgents/tech.lenne.lt-dev-caddy.plist) ou unidade systemd-user (Linux). Aguarda até 8s pelo endpoint admin do Caddy (:2019) responder, valida o arquivo e lembra você de executar sudo -E HOME="$HOME" caddy trust (o -E HOME="$HOME" é obrigatório — sem ele, o sudo muda HOME para /var/root e a instalação do CA falha silenciosamente). NÃO usa brew services start caddy — seu plist codifica --config /opt/homebrew/etc/Caddyfile e causa loop de falhas contra nossa localização do Caddyfile. Encadeia automaticamente: quando executado dentro de um projeto lt-dev não inicializado, executa init depois (--skip-init para optar por não participar).
• uninstall — Contraparte simétrica de install. Remove o LaunchAgent / unidade systemd, remove o arquivo de unidade. Com --purge também exclui ~/.lenneTech/Caddyfile e logs do caddy. NÃO remove o binário caddy em si (use brew uninstall caddy se desejar).
• init (alias migrate) — Idempotente. Constrói a identidade do projeto (slug = nome do package.json, subdomínios a partir do layout do monorepo), corrige port: 3000 / port: 3001 / alvos proxy Vite / URLs Playwright codificados para variantes cientes de env (padrões preservados), persiste em ~/.lenneTech/projects.json, injeta um bloco de URL "Local Development (lt dev)" em todos os arquivos CLAUDE.md, adiciona .lt-dev/ ao .gitignore. Encadeia automaticamente: executa install primeiro quando a máquina ainda não está preparada (--skip-install para optar por não participar).
• up — Aloca portas upstream internas (4000+, nunca 3000/3001), insere ou atualiza o bloco Caddy com reverse_proxy 127.0.0.1:<porta> + recarrega, exporta PORT, HOST=127.0.0.1 / NITRO_HOST=127.0.0.1 (fixa servidores dev ao IPv4 para que o upstream seja 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, o banco de dados da API (MongoDB: NSC__MONGOOSE__URI; PostgreSQL / MySQL / MariaDB, a partir da CLI lt 1.54.0: NSC__DATABASE__URL e NSC__DATABASE__OWNER_URL apenas para a API, em um banco de dados próprio da stack que a primeira inicialização cria como a função proprietária, então o proprietário precisa de CREATEDB no PostgreSQL ou CREATE + GRANT OPTION no MySQL / MariaDB; registrado sem credenciais em dbUrls em ~/.lenneTech/projects.json), NODE_EXTRA_CA_CERTS (CA raiz do Caddy para que o Nuxt SSR confie em HTTPS ao buscar), além de aliases legados API_URL / SITE_URL para projetos que antecedem a convenção NUXT_*. Em seguida, inicia pnpm start (api) + pnpm dev (app) em modo destacado. As verificações pré-inicialização se recusam a iniciar quando o Caddy está faltando, o daemon do Caddy está inativo, uma sessão existente está ativa ou as portas internas estão ocupadas. Logs em <root>/.lt-dev/{api,app}.log.
• down — Envia SIGTERM para o grupo de processos salvo (PID negativo) para que os filhos (Vite, Nest watcher, etc.) também o recebam. Remove o bloco Caddy do projeto + recarrega. Também derruba qualquer stack de teste isolada (lt dev test) para este projeto.
• test — E2E ISOLADO. Inicia uma SEGUNDA stack paralela (<slug>-test.localhost / api.<slug>-test.localhost, próprias portas + bloco Caddy + bridge .lt-dev/.env.test) em um DB dedicado <slug>-test (separado do <slug>-local de desenvolvimento e do <slug>-e2e de teste da API), executa o suite Playwright (global-setup redefine esse DB uma vez antes do primeiro teste) e, em seguida, auto-destroi sem resíduos. Executa lado a lado — e nunca toca — a sessão de desenvolvimento. --keep o mantém ativo; lt dev test down o interrompe; --api executa os testes de API (já isolados); --debug = PWDEBUG+com cabeça; -- <args> encaminha para o Playwright. --shard N executa o conjunto dividido em N stacks TOTALMENTE isoladas em paralelo (cada uma com suas próprias portas + bloco Caddy + DB <slug>-test-<i>) + N processos Playwright --shard=i/N — a matriz de paridade local com CI. Um --shard simples usa como padrão 2 (o ponto ideal estável: N≥3 sobrecarrega os núcleos de desempenho em uma máquina de desenvolvimento típica → instável); --shard auto dimensiona N a partir de CPU+RAM (conservador). Fragmentos locais compartilham UMA máquina (ao contrário dos contêineres por fragmento do CI), então a CLI exporta LT_DEV_TEST_SHARDS para o playwright.config do projeto para relaxar os timeouts sob essa carga apenas (o CI permanece rápido). lt dev test down recupera todos os fragmentos. Requer a versão da CLI lt que oferece esta sessão isolada.
• status / status --all — Projeto atual: subdomínios → portas upstream, URI do banco de dados, PIDs da sessão (ativo/morto), estado upstream lsof em tempo real. --all: cada projeto registrado com um indicador ●/○.
• doctor — Caddy no PATH, lt-dev LaunchAgent / unidade systemd carregada, daemon em execução, Caddyfile válido, portas 80/443 livres ou ocupadas pelo Caddy, *.localhost resolve (loopback IPv4 ou IPv6), status do registro.
• tunnel — Cloudflare Quick Tunnel em primeiro plano: cloudflared tunnel --url https://<slug>.local host --http-host-header <slug>.localhost --no-tls-verify. Imprime uma URL pública *.trycloudflare.com (5-10s) e executa até Ctrl-C. O padrão expõe o App; --api alterna o alvo. Os cookies de autenticação no domínio localhost NÃO são válidos na URL do túnel — adicione a URL do túnel ao trustedOrigins do Better-Auth para que os fluxos de login tenham sucesso. Inicie um segundo lt dev tunnel --api em paralelo para uso externo completo.

Substitua o binário de spawn via LT_PNPM_BIN (por exemplo, para projetos baseados em bun via script wrapper).

lt ticket — Ambientes de desenvolvimento de ticket paralelo

Trabalhe em vários tickets/recursos de UM projeto ao mesmo tempo — cada um em seu PRÓPRIO worktree git + sua PRÓPRIA stack lt dev isolada (URLs próprias, portas, bloco Caddy, DB vazio) — para que vários tickets possam ser testados no navegador E testados E2E em paralelo sem qualquer influência cruzada.

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