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

> Запускайте сгенерированные команды приложения с контекстом среды выполнения Kazzle.

# Kazzle CLI

Используйте Kazzle CLI для запуска команд приложения **в разработке и предпросмотре**:

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

Всё после `--` — это реальная команда. Kazzle сначала внедряет среду выполнения.

`kazzle run` предназначен только для разработки и предпросмотра. Он должен быть в скрипте `dev`, никогда в `start`. В production развёрнутая среда выполнения внедряет `PORT`, `HOST` и секреты напрямую, а production-команда — это голая команда (например `bun run index.ts`). CLI `kazzle` не установлен в развёрнутых образах, поэтому production-команда, вызывающая `kazzle run`, падает с ошибкой `kazzle: command not found`.

## Что внедряет `kazzle run`

* секреты из записи `env` компонента в `kazzle.config.ts`
* `PORT` и `HOST`
* URL соседних компонентов, например `KAZZLE_APP_COMPONENT_SERVER_URL`
* идентификацию среды выполнения Kazzle, такую как ID приложения и имя компонента

## Пример

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

`dev` запускается через `kazzle run`, чтобы Kazzle мог внедрить порт предпросмотра и переменные среды. `start` — это голая команда; production внедряет `PORT`/`HOST`/секреты самостоятельно.

Не помещайте названия коллекций секретов в `package.json`. Поместите их в `kazzle.config.ts`.

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

## Связывание checkout с приложением

`kazzle run` должен знать, какому приложению принадлежит эта директория. Порядок разрешения:

1. `--app=<appId>` в командной строке
2. переменная окружения `KAZZLE_APP_ID` (устанавливается автоматически, когда Kazzle запускает контролируемый компонент)
3. `.kazzle/link.json`, найденный выше от текущей директории

Если ничего из этого не разрешится, `kazzle run` выходит с ошибкой:

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

`app { create: {} }` автоматически записывает `<checkout>/.kazzle/link.json` — как `.vercel/project.json` у Vercel. Файл специфичен для каждого клона и добавлен в gitignore. После свежего `git clone` существующего приложения запустите:

```bash theme={"theme":"material-theme-darker"}
kazzle link              # сопоставить текущую директорию с checkout'ами приложений вашего Space
kazzle link --app=<id>   # принудительно связать конкретное приложение
kazzle unlink            # удалить файл связи
```

ИИ может восстановить отсутствующую связь из thread с помощью `app { link: { appId } }`.