> ## 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

> Uruchamiaj wygenerowane polecenia aplikacji z kontekstem runtime Kazzle.

# Kazzle CLI

Użyj Kazzle CLI do uruchamiania poleceń aplikacji **w trybie development i preview**:

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

Wszystko po `--` to rzeczywiste polecenie. Kazzle najpierw wstrzykuje środowisko runtime.

`kazzle run` jest tylko dla development i preview. Należy do skryptu `dev`, nigdy do `start`. W produkcji wdrożony runtime wstrzykuje `PORT`, `HOST` i sekrety bezpośrednio, a polecenie produkcyjne to polecenie bez obudowy (np. `bun run index.ts`). CLI `kazzle` nie jest zainstalowany w wdrożonych obrazach, więc polecenie produkcyjne wywołujące `kazzle run` kończy się błędem `kazzle: command not found`.

## Co wstrzykuje `kazzle run`

* sekrety z wpisu `env` komponentu w `kazzle.config.ts`
* `PORT` i `HOST`
* adresy URL komponentów równorzędnych, takie jak `KAZZLE_APP_COMPONENT_SERVER_URL`
* tożsamość runtime Kazzle, taką jak ID aplikacji i nazwa komponentu

## Przykład

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

`dev` uruchamia się przez `kazzle run`, aby Kazzle mógł wstrzyknąć port preview i env runtime. `start` to polecenie bez obudowy — produkcja wstrzykuje `PORT`/`HOST`/sekrety sama.

Nie umieszczaj nazw kolekcji sekretów w `package.json`. Umieść je w `kazzle.config.ts`.

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

## Łączenie checkout z aplikacją

`kazzle run` musi wiedzieć, do której aplikacji należy ten katalog. Kolejność rozwiązywania:

1. `--app=<appId>` w wierszu polecenia
2. zmienna środowiskowa `KAZZLE_APP_ID` (ustawiana automatycznie, gdy Kazzle uruchamia nadzorowany komponent)
3. \`\`.kazzle/link.json\` przeszukiwany od bieżącego katalogu

Jeśli żaden z nich nie rozwiąże problemu, `kazzle run` kończy się błędem:

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

`app { create: {} }` automatycznie zapisuje `<checkout>/.kazzle/link.json` — podobnie jak `.vercel/project.json` Vercela. Plik jest per-clone i gitignorowany. Po świeżym `git clone` istniejącej aplikacji uruchom:

```bash theme={"theme":"material-theme-darker"}
kazzle link              # dopasuj bieżący katalog do checkoutów aplikacji w Twojej Space
kazzle link --app=<id>   # wymuś konkretną aplikację
kazzle unlink            # usuń plik linku
```

AI może naprawić brakujący link z wątku za pomocą `app { link: { appId } }`.