lenneTech/lt-cli

Référence CLI LT

Pièges

• lt fullstack init sans --noConfirm bloque Claude Code indéfiniment — Les invites interactives (nom du projet, init git, sélection de template) attendent une entrée stdin. Claude Code ne peut pas y répondre, et la session se bloque sur "Dépliage..." sans consommer de jetons. Passez --noConfirm + tous les indicateurs requis (--name X --frontend nuxt --git false) lorsque vous appelez la CLI lt depuis Claude Code.
• --api-link et --frontend-link créent des LIENS SYMBOLIQUES, pas des copies — Les modifications apportées au template checkout (nest-server-starter, nuxt-base-starter), où qu'il se trouve sur cette machine, affectent immédiatement le projet lié. C'est une fonctionnalité pour le développement de framework mais surprend les développeurs qui s'attendent à des copies. Documentez-le dans le README du projet lorsque vous utilisez --api-link.
• lt git reset est DESTRUCTEUR et irréversible — Se trouve à côté du lt git get sécurisé dans le menu CLI. reset effectue git reset --hard suivi d'un force-pull, détruisant TOUTES les modifications locales sans confirmation. Ne l'exécutez jamais sur une branche avec du travail non poussé. Préférez git stash + lt git get.
• lt serveur object X --controller génère REST, PAS GraphQL — La valeur par défaut est REST. Pour les projets GraphQL, utilisez --resolver. La CLI ne détecte pas automatiquement les modèles de projet existants — vous devez spécifier explicitement.
• lt fullstack convert-mode réécrit l'arborescence source — Le basculement entre les modes npm et vendor déplace le code du framework dans/depuis src/core/ (API) ou app/core/ (App). L'opération est réversible mais PAS idempotente en cours d'exécution — validez toujours avant de commencer, afin qu'une conversion échouée puisse être annulée via git reset.
• --next est expérimental et incompatible avec lt serveur module/object/addProp/test/permissions — Lorsque lt serveur create --next ou lt fullstack init --next est utilisé, l'API est clonée depuis nest-base (Bun + Prisma 7 + Postgres + Better-Auth) au lieu de nest-server-starter. Les générateurs en aval ciblent la disposition nest-server classique (modèles Mongoose, src/serveur/modules/, etc.) et ne fonctionneront pas sur un projet nest-base. Utilisez-le uniquement pour le prototypage greenfield ; pour le travail en production, préférez le template par défaut.
• macOS : un $TMPDIR long casse Nuxt SSR sous lt dev up — Sur macOS, $TMPDIR est un long chemin par utilisateur (/var/folders/…, souvent >~49 caractères). Le vite-node de Nuxt 4.4.7 construit un chemin de socket de domaine Unix sous celui-ci qui dépasse la limite de 104 caractères du système d'exploitation → SSR plante avec une erreur 500. Solution de contournement : démarrez avec un répertoire tmp court, TMPDIR=/tmp lt dev up. (Linux $TMPDIR=/tmp est court, donc cela n'affecte que macOS.)
• macOS : le port WebSocket HMR 24678 entre en collision entre les projets lt dev parallèles — Deux projets lt dev exécutés en même temps tentent tous deux de lier le port WS HMR 24678 de Vite. vite.server.hmr.port est ignoré par Nuxt 4.4.7, vous ne pouvez donc pas le réaffecter dans la configuration. C'est non fatal — la recompilation SSR fonctionne toujours ; seules les mises à jour HMR en direct sur le second projet sont affectées. Rechargez la page pour récupérer les modifications là-bas.

Limites du skill

Intention de l'utilisateur	Skill correct
"lt fullstack init"	CE SKILL
"lt git get feature-branch"	CE SKILL
"lt serveur create mon-projet"	CE SKILL
"lt serveur module / object / addProp"	generating-nest-servers
"lt serveur permissions"	generating-nest-servers
"Créer un module NestJS"	generating-nest-servers
"Construire un composant Vue"	developing-lt-frontend
"lt déploiement create"	CE SKILL (voir la commande lt déploiement create)
"Déployer sur TurboOps / go live / turbo deploy / déploiement stage"	deploying-to-turboops

Après lt fullstack init :

• Travail backend (projets/api/) → generating-nest-servers
• Travail frontend (projets/app/) → developing-lt-frontend

Commandes

lt git get — Checkout/Créer une branche

lt git get <nom-branche>    # alias : lt git g

1. La branche existe localement → bascule dessus
2. La branche existe sur le remote → la checkout et la suit
3. Ni l'un ni l'autre n'existe → crée une nouvelle branche depuis la branche courante

lt git reset — Réinitialiser vers le remote

lt git reset

Récupère la dernière version du remote, réinitialise la branche courante vers origin/<branche>. Destructeur — toutes les modifications locales sont perdues.

lt fullstack init — Créer un espace de travail fullstack

# Non interactif
lt fullstack init --name <Nom> --frontend <angular|nuxt> --git <true|false> --noConfirm \
  [--git-link <URL>] [--api-link <chemin>] [--frontend-link <chemin>] [--next]

Paramètre	Requis	Description
--name	Oui	Nom de l'espace de travail (PascalCase)
--frontend	Oui	angular ou nuxt
--git	Oui	Initialiser git : true / false
--noConfirm	Non	Ignorer les invites de confirmation
--git-link	Non	URL du dépôt Git
--api-branch	Non	Branche de nest-server-starter
--frontend-branch	Non	Branche du starter frontend
--api-copy / --api-link	Non	Template API local (copie / lien symbolique)
--frontend-copy / --frontend-link	Non	Template frontend local (copie / lien symbolique)
--next	Non	Expérimental — clone nest-base (Bun + Prisma 7 + Postgres + Better-Auth) pour l'API. Force apiMode = Rest, frameworkMode = npm, et saute l'installation de l'espace de travail (exécutez pnpm install pour l'application et bun install pour l'API manuellement). Les lt serveur module/object/addProp/test en aval NE sont PAS compatibles avec la disposition résultante.

Priorité : --*-link > --*-copy > --*-branch > défaut (clone GitHub)

Structure créée :

<espace-de-travail>/
├── projets/
│   ├── api/    ← nest-server-starter (ou nest-base avec --next)
│   └── app/    ← nuxt-base-starter (ou ng-base-starter)
├── package.json
└── .gitignore

Après création :

cd <espace-de-travail> && pnpm install
lt dev init                      # idempotent : patches ENV + enregistrement ; exécute automatiquement `lt dev install` d'abord si la machine n'est pas encore configurée
lt dev up                        # Démarre l'API + l'App derrière Caddy sous https://<slug>.localhost

# Avec --next : installer par sous-projet, pas d'installation de l'espace de travail
cd <espace-de-travail>/projets/app && pnpm install
cd <espace-de-travail>/projets/api && bun install

(Revient à pnpm -r --parallel run start sur les ports par défaut 3000/3001 si lt dev n'est pas utilisé.)

lt dev — Orchestration de projets parallèles (Caddy + HTTPS)

Sert chaque projet lt sous des URLs HTTPS stables (<slug>.localhost, api.<slug>.localhost) via Caddy afin que plusieurs projets puissent fonctionner côte à côte sans collision sur 3000/3001 et sans interconnexion d'authentification. Utilisez ceci dans chaque projet lt-monorepo ou API/App autonome.

lt dev install                   # Une fois par machine : amorce un LaunchAgent dédié/unité systemd + stub Caddyfile + rappel CA
lt dev uninstall [--purge]       # Supprime le service lt-dev (--purge supprime également Caddyfile + logs)
lt dev init                      # Une fois par projet (idempotent) : patches ENV + enregistrement
lt dev up                        # Démarre l'API + l'App derrière Caddy
lt dev down                      # Arrête les processus + supprime le bloc Caddy (démolit également toute pile de test isolée)
lt dev test                      # E2E Playwright ISOLÉ : pile parallèle + DB dédiée `<slug>-test`, auto-démolition
lt dev test --shard              # Fragmenter sur 2 piles isolées (défaut — le bon équilibre stable)
lt dev test --shard 3            # Fragmenter sur N piles isolées (chacune ses ports/Caddy/DB `<slug>-test-<i>`)
lt dev test --shard auto         # Taille N basée sur le CPU + RAM de cette machine (conservateur)
lt dev test down                 # Démolit la/les piles de test isolée(s) (sans résidus)
lt dev status                    # Affiche les URLs + PIDs + état amont en direct pour CE projet (incluant toute pile de test)
lt dev status --all              # Liste chaque projet enregistré + état d'exécution
lt dev doctor                    # Diagnostique les problèmes Caddy / CA / DNS / port
lt dev tunnel [--api]            # Tunnel Cloudflare Quick en premier plan : URL publique *.trycloudflare.com

Ce que fait chaque sous-commande :

• install — Une fois par machine. Vérifie que caddy est dans le PATH (suggère brew install caddy si manquant), crée le stub ~/.lenneTech/Caddyfile, écrit et amorce un LaunchAgent dédié (macOS, ~/Library/LaunchAgents/tech.lenne.lt-dev-caddy.plist) ou une unité systemd-user (Linux). Attend jusqu'à 8s que le point de terminaison admin de Caddy (:2019) réponde, valide le fichier, et vous rappelle d'exécuter sudo -E HOME="$HOME" caddy trust (le -E HOME="$HOME" est obligatoire — sans cela sudo change HOME en /var/root et l'installation CA échoue silencieusement). N'utilise PAS brew services start caddy — son plist code en dur --config /opt/homebrew/etc/Caddyfile et boucle en crash sur notre emplacement Caddyfile. Chaîne automatique : lorsqu'il est exécuté dans un projet lt-dev non initialisé, exécute init après (--skip-init pour refuser).
• uninstall — Contrepartie symétrique de install. Supprime le LaunchAgent / l'unité systemd, supprime le fichier d'unité. Avec --purge, supprime également ~/.lenneTech/Caddyfile et les logs caddy. Ne supprime pas le binaire caddy lui-même (utilisez brew uninstall caddy si souhaité).
• init (alias migrate) — Idempotent. Construit l'identité du projet (slug = package.json "name", sous-domaines à partir de la disposition du monorepo), corrige les port: 3000 / port: 3001 / cibles proxy Vite / URLs Playwright codés en dur en variantes sensibles à l'environnement (valeurs par défaut préservées), persiste dans ~/.lenneTech/projects.json, injecte un bloc "Développement local (lt dev)" dans tous les fichiers CLAUDE.md, ajoute .lt-dev/ à .gitignore. Chaîne automatique : exécute install d'abord lorsque la machine n'est pas encore préparée (--skip-install pour refuser).
• up — Alloue des ports amont internes (4000+, jamais 3000/3001), insère ou met à jour le bloc Caddy avec reverse_proxy 127.0.0.1:<port> + recharge, exporte PORT, HOST=127.0.0.1 / NITRO_HOST=127.0.0.1 (épingle les serveurs de développement à IPv4 afin que l'amont soit sans ambiguïté), 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 base de données de l'API (MongoDB : NSC__MONGOOSE__URI ; PostgreSQL / MySQL / MariaDB, à partir de la CLI lt 1.54.0 : NSC__DATABASE__URL et NSC__DATABASE__OWNER_URL pour l'API uniquement, sur une base de données de la propre pile que le premier démarrage crée en tant que rôle propriétaire, donc le propriétaire a besoin de CREATEDB sur PostgreSQL ou CREATE + GRANT OPTION sur MySQL / MariaDB ; enregistré sans informations d'identification sous dbUrls dans ~/.lenneTech/projects.json), NODE_EXTRA_CA_CERTS (CA racine Caddy pour que les requêtes Nuxt SSR fassent confiance à HTTPS), plus des alias hérités API_URL / SITE_URL pour les projets qui précèdent la convention NUXT_*. Ensuite, lance pnpm start (api) + pnpm dev (app) de manière détachée. Les vérifications préalables refusent de démarrer lorsque Caddy est manquant, le démon Caddy est arrêté, une session existante est active ou les ports internes sont liés. Logs dans <root>/.lt-dev/{api,app}.log.
• down — Envoie SIGTERM au groupe de processus enregistré (PID négatif) afin que les enfants (Vite, observateur Nest, etc.) le reçoivent également. Supprime le bloc Caddy du projet + recharge. Démolit également toute pile de test isolée (lt dev test) pour ce projet.
• test — E2E ISOLÉ. Met en place une DEUXIÈME pile parallèle (<slug>-test.localhost / api.<slug>-test.localhost, propres ports + bloc Caddy + pont .lt-dev/.env.test) sur une DB dédiée <slug>-test (séparée du <slug>-local de développement et du <slug>-e2e de test API), exécute la suite Playwright (la configuration globale réinitialise cette DB une fois avant le premier test), puis auto-démolit sans résidus. S'exécute parallèlement — et ne touche jamais — la session de développement. --keep la laisse active ; lt dev test down l'arrête ; --api exécute les tests API (déjà isolés) à la place ; --debug = PWDEBUG+avec tête ; -- <args> transmet à Playwright. --shard N exécute la suite divisée sur N piles ENTIÈREMENT isolées en parallèle (chacune ses propres ports + bloc Caddy + DB <slug>-test-<i>) + N processus Playwright --shard=i/N — la matrice de parité CI locale. Un simple --shard par défaut à 2 (le bon équilibre stable : N≥3 surcharge les cœurs de performance sur une machine de développement typique → instable) ; --shard auto dimensionne N à partir du CPU+RAM (conservateur). Les fragments locaux partagent UNE machine (contrairement aux conteneurs par fragment du CI), donc la CLI exporte LT_DEV_TEST_SHARDS pour que le playwright.config du projet assouplisse les délais d'attente sous cette charge uniquement (le CI reste rapide). lt dev test down récupère tous les fragments. Nécessite la version de la CLI lt qui fournit cette session isolée.
• status / status --all — Projet actuel : sous-domaines → ports amont, URI DB, PIDs de session (actif/mort), état amont lsof en direct. --all : chaque projet enregistré avec un indicateur ●/○.
• doctor — Caddy dans le PATH, lt-dev LaunchAgent / unité systemd chargée, démon en cours d'exécution, Caddyfile valide, ports 80/443 libres ou détenus par Caddy, *.localhost résout (boucle locale IPv4 ou IPv6), état du registre.
• tunnel — Tunnel Cloudflare Quick en premier plan : cloudflared tunnel --url https://<slug>.localhost --http-host-header <slug>.localhost --no-tls-verify. Affiche une URL publique *.trycloudflare.com (5-10s) et s'exécute jusqu'à Ctrl-C. Par défaut expose l'App ; --api change la cible. Les cookies d'authentification sur le domaine localhost ne sont PAS valides sur l'URL du tunnel — ajoutez l'URL du tunnel à trustedOrigins de Better-Auth pour que les flux de connexion réussissent. Démarrez un second lt dev tunnel --api en parallèle pour une utilisation externe complète.

Remplacez le binaire de lancement via LT_PNPM_BIN (par exemple, pour les projets basés sur bun via un script wrapper).

lt ticket — Environnements de développement de tickets parallèles

Travaillez sur plusieurs tickets/fonctionnalités d'UN projet en même temps — chacun dans son PROPRE git worktree + sa PROPRE pile lt dev isolée (propres URLs, ports, bloc Caddy, DB vide) — afin que plusieurs tickets puissent être testés dans le navigateur ET en E2E en parallèle sans aucune influence croisée.

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