lenneTech/using-lt-cli

LT CLI Referenz

Fallstricke

• lt fullstack init ohne --noConfirm blockiert Claude Code dauerhaft — Die interaktiven Eingabeaufforderungen (Projektname, Git-Initialisierung, Template-Auswahl) warten auf stdin-Eingabe. Claude Code kann nicht darauf reagieren, und die Sitzung hängt in „Unfurling...“ ohne Token-Verbrauch. Verwenden Sie --noConfirm zusammen mit allen erforderlichen Flags (--name X --frontend nuxt --git false), wenn Sie das lt CLI aus Claude Code aufrufen.
• --api-link und --frontend-link erstellen SYMLINKS, keine Kopien — Änderungen am Template-Checkout (nest-server-starter, nuxt-base-starter), wo auch immer es sich auf diesem Rechner befindet, wirken sich sofort auf das verlinkte Projekt aus. Dies ist ein Feature für die Framework-Entwicklung, aber Entwickler, die Kopien erwarten, werden überrascht. Dokumentieren Sie dies in der Projekt-README, wenn Sie --api-link verwenden.
• lt git reset ist ZERSTÖREND und unwiderruflich — Befindet sich im CLI-Menü neben dem sicheren lt git get. reset führt git reset --hard gefolgt von Force-Pull aus und zerstört ALLE lokalen Änderungen ohne Bestätigung. Führen Sie dies niemals auf einem Branch mit nicht-gepushter Arbeit aus. Bevorzugen Sie git stash + lt git get.
• lt server object X --controller generiert REST, NICHT GraphQL — Standardmäßig wird REST verwendet. Verwenden Sie für GraphQL-Projekte --resolver. Das CLI erkennt dies nicht automatisch anhand vorhandener Projektmuster – Sie müssen es explizit angeben.
• lt fullstack convert-mode schreibt den Quellbaum um — Beim Wechsel zwischen npm- und vendor-Modus wird Framework-Code in/aus src/core/ (API) oder app/core/ (App) verschoben. Die Operation ist umkehrbar, aber NICHT idempotent während der Ausführung – committen Sie immer vor dem Start, damit eine fehlgeschlagene Konvertierung via git reset rückgängig gemacht werden kann.
• --next ist experimentell und inkompatibel mit lt server module/object/addProp/test/permissions — Wenn lt server create --next oder lt fullstack init --next verwendet wird, wird die API von nest-base (Bun + Prisma 7 + Postgres + Better-Auth) anstelle von nest-server-starter geklont. Die nachgelagerten Generatoren zielen auf das klassische nest-server-Layout ab (Mongoose-Modelle, src/server/modules/, etc.) und funktionieren nicht mit einem nest-base-Projekt. Verwenden Sie dies nur für Greenfield-Prototypen; für die Produktion bevorzugen Sie das Standard-Template.
• macOS: Ein langes $TMPDIR bricht Nuxt SSR unter lt dev up — Unter macOS ist $TMPDIR ein langer benutzerspezifischer Pfad (/var/folders/…, oft >~49 Zeichen). Nuxt 4.4.7s vite-node baut einen Unix-Domain-Socket-Pfad darunter, der das OS-Limit von 104 Zeichen überschreitet → SSR stürzt mit 500 ab. Workaround: Starten Sie mit einem kurzen tmp-Verzeichnis, TMPDIR=/tmp lt dev up. (Linux $TMPDIR=/tmp ist kurz, daher tritt dies nur unter macOS auf.)
• macOS: HMR WebSocket-Port 24678 kollidiert zwischen parallelen lt dev-Projekten — Zwei gleichzeitig laufende lt dev-Projekte versuchen beide, Vites HMR-WS-Port 24678 zu binden. vite.server.hmr.port wird von Nuxt 4.4.7 ignoriert, daher kann der Port nicht in der Konfiguration neu zugewiesen werden. Dies ist nicht fatal – die SSR-Neucompilierung funktioniert weiterhin; nur Live-HMR-Pushes auf dem zweiten Projekt sind betroffen. Laden Sie die Seite neu, um Änderungen dort zu übernehmen.

Skill-Grenzen

Benutzerabsicht	Richtiges Skill
„lt fullstack init“	DIESES SKILL
„lt git get feature-branch“	DIESES SKILL
„lt server create my-project“	DIESES SKILL
„lt server module / object / addProp“	generating-nest-servers
„lt server permissions“	generating-nest-servers
„Erstelle ein NestJS-Modul“	generating-nest-servers
„Erstelle eine Vue-Komponente“	developing-lt-frontend
„lt deployment create“	DIESES SKILL (siehe den Befehl lt deployment create)
„Nach TurboOps deployen / live gehen / turbo deploy / Deployment-Stage“	deploying-to-turboops

Nach lt fullstack init:

• Backend-Arbeit (projects/api/) → generating-nest-servers
• Frontend-Arbeit (projects/app/) → developing-lt-frontend

Befehle

lt git get — Branch auschecken/erstellen

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

1. Branch existiert lokal → wechselt zu ihm
2. Branch existiert auf Remote → checked aus und verfolgt ihn
3. Keiner existiert → erstellt neuen Branch vom aktuellen aus

lt git reset — Auf Remote zurücksetzen

lt git reset

Holt die neuesten Daten vom Remote, setzt den aktuellen Branch auf origin/<branch> zurück. Zerstörend — alle lokalen Änderungen gehen verloren.

lt fullstack init — Fullstack-Workspace erstellen

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

Parameter	Erforderlich	Beschreibung
--name	Ja	Workspace-Name (PascalCase)
--frontend	Ja	angular oder nuxt
--git	Ja	Git initialisieren: true / false
--noConfirm	Nein	Bestätigungsaufforderungen überspringen
--git-link	Nein	Git-Repository-URL
--api-branch	Nein	Branch von nest-server-starter
--frontend-branch	Nein	Branch des Frontend-Starters
--api-copy / --api-link	Nein	Lokales API-Template (Kopie / Symlink)
--frontend-copy / --frontend-link	Nein	Lokales Frontend-Template (Kopie / Symlink)
--next	Nein	Experimentell — Klont nest-base (Bun + Prisma 7 + Postgres + Better-Auth) für die API. Erzwingt apiMode = Rest, frameworkMode = npm und überspringt die Workspace-Installation (führen Sie pnpm install für die App und bun install für die API manuell aus). Nachgelagerte lt server module/object/addProp/test sind NICHT kompatibel mit dem resultierenden Layout.

Priorität: --*-link > --*-copy > --*-branch > Standard (GitHub-Klon)

Erstellte Struktur:

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

Nach der Erstellung:

cd <workspace> && pnpm install
lt dev init                      # Idempotent: ENV-Patches + Registrierung; führt automatisch `lt dev install` aus, wenn der Rechner noch nicht eingerichtet ist
t dev up                        # Starte API + App hinter Caddy unter https://<slug>.localhost

# Mit --next: Installation pro Unterprojekt, keine Workspace-Installation
cd <workspace>/projects/app && pnpm install
cd <workspace>/projects/api && bun install

(Fällt auf pnpm -r --parallel run start auf den Standard-Ports 3000/3001 zurück, wenn lt dev nicht verwendet wird.)

lt dev — Parallele Projekt-Orchestrierung (Caddy + HTTPS)

Stellt jedes lt-Projekt unter stabilen HTTPS-URLs (<slug>.localhost, api.<slug>.localhost) via Caddy bereit, sodass mehrere Projekte nebeneinander laufen können, ohne auf Port 3000/3001 zu kollidieren und ohne Auth-Überkreuzverbindungen. Verwenden Sie dies in jedem lt-Monorepo oder eigenständigen API/App-Projekt.

lt dev install                   # Einmalig pro Rechner: Bootstrapt dedizierten LaunchAgent/systemd-Dienst + Caddyfile-Stub + CA-Erinnerung
lt dev uninstall [--purge]       # Entferne den lt-dev-Dienst (--purge löscht auch Caddyfile + Logs)
lt dev init                      # Einmalig pro Projekt (idempotent): ENV-Patches + Registrierung
lt dev up                        # Starte API + App hinter Caddy
lt dev down                      # Stoppe Prozesse + entferne Caddy-Block (baut auch isolierte Test-Stacks ab)
t dev test                       # ISOLIERTES Playwright E2E: paralleler Stack + dedizierte `<slug>-test`-DB, automatischer Abbau
lt dev test --shard              # Auf 2 isolierte Stacks aufteilen (Standard — stabiler Sweet Spot)
lt dev test --shard 3            # Auf N isolierte Stacks aufteilen (jeweils eigene Ports/Caddy/DB `<slug>-test-<i>`)
t dev test --shard auto          # N Größe basierend auf CPU + RAM dieses Rechners (konservativ)
lt dev test down                 # Baue den/die isolierten Test-Stack(s) ab (rückstandsfrei)
lt dev status                    # Zeige URLs + PIDs + Live-Upstream-Status für DIESES Projekt (inkl. etwaiger Test-Stacks)
t dev status --all               # Liste jedes registrierte Projekt + Laufzustand auf
lt dev doctor                    # Diagnostiziere Caddy / CA / DNS / Port-Probleme
t dev tunnel [--api]             # Vordergrund-Cloudflare-Quick-Tunnel: öffentliche *.trycloudflare.com-URL

Was jeder Unterbefehl tut:

• install — Einmalig pro Rechner. Überprüft, ob caddy im PATH ist (schlägt brew install caddy vor, falls nicht), erstellt ~/.lenneTech/Caddyfile-Stub, schreibt + bootstrapt einen dedizierten LaunchAgent (macOS, ~/Library/LaunchAgents/tech.lenne.lt-dev-caddy.plist) oder systemd-user-Dienst (Linux). Wartet bis zu 8s auf den Caddy-Admin-Endpunkt (:2019), validiert die Datei und erinnert Sie daran, sudo -E HOME="$HOME" caddy trust auszuführen (das -E HOME="$HOME" ist zwingend erforderlich – ohne setzt sudo HOME auf /var/root und die CA-Installation schlägt still fehl). Verwendet NICHT brew services start caddy – dessen plist hardcodiert --config /opt/homebrew/etc/Caddyfile und stürzt in einer Endlosschleife gegen unseren Caddyfile-Speicherort ab. Auto-verkettet: Wenn innerhalb eines nicht initialisierten lt-dev-Projekts ausgeführt, führt es danach init aus (--skip-init zum Opt-out).
• uninstall — Symmetrisches Gegenstück zu install. Entfernt den LaunchAgent / systemd-Dienst, löscht die Unit-Datei. Mit --purge wird auch ~/.lenneTech/Caddyfile und Caddy-Logs gelöscht. Entfernt NICHT das Caddy-Binary selbst (verwenden Sie brew uninstall caddy falls gewünscht).
• init (Alias migrate) — Idempotent. Baut die Projektidentität auf (slug = package.json "name", Subdomains aus dem Monorepo-Layout), patcht veraltete hartcodierte port: 3000 / port: 3001 / Vite-Proxy-Ziele / Playwright-URLs auf umgebungsbewusste Varianten (Standards bleiben erhalten), persistiert in ~/.lenneTech/projects.json, fügt einen „Lokale Entwicklung (lt dev)" URL-Block in alle CLAUDE.md-Dateien ein, fügt .lt-dev/ zu .gitignore hinzu. Auto-verkettet: Führt zuerst install aus, wenn der Rechner noch nicht vorbereitet ist (--skip-install zum Opt-out).
• up — Weist interne Upstream-Ports zu (4000+, niemals 3000/3001), erstellt oder aktualisiert den Caddy-Block mit reverse_proxy 127.0.0.1:<port> + lädt neu, exportiert PORT, HOST=127.0.0.1 / NITRO_HOST=127.0.0.1 (fixiert Dev-Server auf IPv4, sodass der Upstream eindeutig ist), BASE_URL, APP_URL, NUXT_API_URL, NUXT_PUBLIC_API_URL, NUXT_PUBLIC_SITE_URL, NUXT_PUBLIC_STORAGE_PREFIX, NUXT_PUBLIC_API_PROXY=false, die API-Datenbank (MongoDB: NSC__MONGOOSE__URI; PostgreSQL / MySQL / MariaDB, ab lt CLI 1.54.0: NSC__DATABASE__URL und NSC__DATABASE__OWNER_URL nur für die API, auf einer eigenen Datenbank des Stacks, die beim ersten Start als Besitzer-Rolle erstellt wird, daher benötigt der Besitzer CREATEDB auf PostgreSQL oder CREATE + GRANT OPTION auf MySQL / MariaDB; aufgezeichnet ohne Anmeldedaten unter dbUrls in ~/.lenneTech/projects.json), NODE_EXTRA_CA_CERTS (Caddy-Root-CA, damit Nuxt SSR HTTPS-Vertrauen hat), plus Legacy-Aliase API_URL / SITE_URL für Projekte, die älter sind als die NUXT_*-Konvention. Startet dann pnpm start (api) + pnpm dev (app) im Hintergrund. Vorab-Checks verweigern den Start, wenn Caddy fehlt, der Caddy-Daemon nicht läuft, eine bestehende Sitzung aktiv ist oder interne Ports bereits belegt sind. Logs in <root>/.lt-dev/{api,app}.log.
• down — Sendet SIGTERM an die gespeicherte Prozessgruppe (negative PID), sodass auch Kindprozesse (Vite, Nest-Watcher usw.) es erhalten. Entfernt den Caddy-Block des Projekts + lädt neu. Baut auch alle isolierten Test-Stacks (lt dev test) für dieses Projekt ab.
• test — ISOLIERTES E2E. Startet einen ZWEITEN, parallelen Stack (<slug>-test.localhost / api.<slug>-test.localhost, eigene Ports + Caddy-Block + .lt-dev/.env.test-Brücke) mit einer dedizierten DB <slug>-test (getrennt von der Dev-<slug>-local und der API-Test-<slug>-e2e), führt die Playwright-Suite aus (global-setup setzt diese DB einmal vor dem ersten Test zurück), baut dann automatisch rückstandsfrei ab. Läuft parallel zur Dev-Sitzung und berührt sie nie. --keep lässt sie laufen; lt dev test down stoppt sie; --api führt stattdessen die (bereits isolierten) API-Tests aus; --debug = PWDEBUG+headed; -- <args> leitet an Playwright weiter. --shard N führt die Suite aufgeteilt auf N VOLLSTÄNDIG isolierte parallele Stacks aus (jeweils eigene Ports + Caddy-Block + DB <slug>-test-<i>) + N --shard=i/N Playwright-Prozesse — die lokale CI-Paritätsmatrix. Ein nacktes --shard verwendet standardmäßig 2 (den stabilen Sweet Spot: N≥3 überlastet die Performance-Kerne eines typischen Entwicklungsrechners → instabil); --shard auto berechnet N aus CPU+RAM (konservativ). Lokale Shards teilen sich EINEN Rechner (anders als die pro-Shard-Container in CI), daher exportiert das CLI LT_DEV_TEST_SHARDS für das playwright.config des Projekts, um Timeouts unter dieser Last nur dort zu lockern (CI bleibt schnell). lt dev test down räumt alle Shards auf. Erfordert die lt-CLI-Version, die diese isolierte Sitzung bereitstellt.
• status / status --all — Aktuelles Projekt: Subdomains → Upstream-Ports, DB-URI, Sitzungs-PIDs (lebend/tot), Live-lsof-Upstream-Status. --all: Jedes registrierte Projekt mit einem ●/○-Indikator.
• doctor — Caddy im PATH, lt-dev-LaunchAgent / systemd-Dienst geladen, Daemon läuft, Caddyfile gültig, Ports 80/443 frei oder von Caddy belegt, *.localhost aufgelöst (IPv4- oder IPv6-Loopback), Registry-Status.
• tunnel — Vordergrund-Cloudflare-Quick-Tunnel: cloudflared tunnel --url https://<slug>.localhost --http-host-header <slug>.localhost --no-tls-verify. Gibt eine öffentliche *.trycloudflare.com-URL aus (5-10s) und läuft bis Ctrl-C. Standardmäßig wird die App bereitgestellt; --api wechselt das Ziel. Auth-Cookies auf der localhost-Domain sind NICHT auf der Tunnel-URL gültig — fügen Sie die Tunnel-URL zu Better-Auths trustedOrigins hinzu, damit Login-Flows erfolgreich sind. Starten Sie einen zweiten lt dev tunnel --api parallel für vollständige externe Nutzung.

Überschreiben des Start-Binärprogramms via LT_PNPM_BIN (z.B. für bun-basierte Projekte via Wrapper-Skript).

lt ticket — Parallele Ticket-Entwicklungsumgebungen

Arbeiten Sie an mehreren Tickets/Features EINES Projekts gleichzeitig — jedes in seinem EIGENEN Git-Worktree + seinem EIGENEN isolierten lt dev-Stack (eigene URLs, Ports, Caddy-Block, leere DB) — sodass mehrere Tickets parallel im Browser getestet UND E2E-getestet werden können, ohne gegenseitige Beeinflussung.

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

(gekürzt für die Übersetzung)