> ## 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` 中。在生產環境中，已部署的執行時會直接注入 `PORT`、`HOST` 和機密，生產命令是裸命令（例如 `bun run index.ts`）。`kazzle` CLI 未安裝在已部署的映像中，因此呼叫 `kazzle run` 的生產命令會因 `kazzle: command not found` 而崩潰。

## `kazzle run` 注入的內容

* 來自 `kazzle.config.ts` 中元件 `env` 項目的機密
* `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` 是裸命令 — 生產環境自行注入 `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' },
  },
]
```

## 將簽出連結到應用程式

`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 的 `.vercel/project.json`。該檔案是按複製版本的，並被 gitignore。在現有應用程式的全新 `git clone` 後，執行：

```bash theme={"theme":"material-theme-darker"}
kazzle link              # 將目前目錄與您的 Space 的應用程式簽出相符
kazzle link --app=<id>   # 強制指定應用程式
kazzle unlink            # 刪除連結檔案
```

AI 可以透過執行緒中的 `app { link: { appId } }` 修復遺失的連結。