> ## 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。在克隆现有应用后，运行：

```bash theme={"theme":"material-theme-darker"}
kazzle link              # 将当前目录与你的 Space 中的应用检出匹配
kazzle link --app=<id>   # 强制指定应用
kazzle unlink            # 删除链接文件
```

AI 可以通过线程中的 `app { link: { appId } }` 修复缺失的链接。