> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kazzle CLI

> Führe generierte App-Befehle mit Kazzle-Laufzeitkontext aus.

# Kazzle CLI

Verwende die Kazzle CLI, um App-Befehle **in Entwicklung und Vorschau** auszuführen:

```bash theme={"theme":"material-theme-darker"}
kazzle run -- <command>
```

Alles nach `--` ist der eigentliche Befehl. Kazzle injiziert zuerst die Laufzeitumgebung.

`kazzle run` ist nur für Entwicklung und Vorschau gedacht. Es gehört ins `dev`-Skript, niemals in `start`. In der Produktion injiziert die bereitgestellte Laufzeit `PORT`, `HOST` und Secrets direkt, und der Produktionsbefehl ist der reine Befehl (z. B. `bun run index.ts`). Die `kazzle` CLI ist nicht in bereitgestellten Images installiert, daher stürzt ein Produktionsbefehl, der `kazzle run` aufruft, mit `kazzle: command not found` ab.

## Was `kazzle run` injiziert

* Secrets aus dem `env`-Eintrag der Komponente in `kazzle.config.ts`
* `PORT` und `HOST`
* URLs von Geschwisterkomponenten wie `KAZZLE_APP_COMPONENT_SERVER_URL`
* Kazzle-Laufzeitidentität wie App-ID und Komponentenname

## Beispiel

```json theme={"theme":"material-theme-darker"}
{
  "scripts": {
    "dev": "kazzle run -- bun --watch server/index.ts",
    "start": "bun server/index.ts"
  }
}
```

`dev` läuft durch `kazzle run`, damit Kazzle den Vorschauport und die Laufzeitumgebung injizieren kann. `start` ist der reine Befehl — die Produktion injiziert `PORT`/`HOST`/Secrets selbst.

Gib keine Secret-Sammlungsnamen in `package.json` an. Gib sie in `kazzle.config.ts` an.

```ts theme={"theme":"material-theme-darker"}
components: [
  {
    name: 'server',
    type: 'process',
    path: './server/index.ts',
    env: { collection: 'my-app', environment: 'local' },
  },
]
```

## Einen Checkout mit einer App verknüpfen

`kazzle run` muss wissen, zu welcher App dieses Verzeichnis gehört. Auflösungsreihenfolge:

1. `--app=<appId>` in der Befehlszeile
2. `KAZZLE_APP_ID` Umgebungsvariable (wird automatisch gesetzt, wenn Kazzle eine überwachte Komponente startet)
3. `.kazzle/link.json` vom aktuellen Verzeichnis aufwärts

Wenn keine dieser Optionen funktioniert, beendet sich `kazzle run` mit:

```
Error: This directory is not linked to a Kazzle app. Run `kazzle link` to fix.
```

`app { create: {} }` schreibt `<checkout>/.kazzle/link.json` automatisch — wie Vercels `.vercel/project.json`. Die Datei ist pro Klon und wird ignoriert. Nach einem frischen `git clone` einer vorhandenen App führe aus:

```bash theme={"theme":"material-theme-darker"}
kazzle link              # match the current directory against your space's app checkouts
kazzle link --app=<id>   # force a specific app
kazzle unlink            # delete the link file
```

Die KI kann einen fehlenden Link aus einem Thread mit `app { link: { appId } }` reparieren.