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

> Chạy các lệnh ứng dụng được tạo với ngữ cảnh runtime của Kazzle.

# Kazzle CLI

Sử dụng Kazzle CLI để chạy các lệnh ứng dụng **trong phát triển và xem trước**:

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

Mọi thứ sau `--` là lệnh thực tế. Kazzle sẽ tiêm môi trường runtime trước.

`kazzle run` chỉ dành cho phát triển và xem trước. Nó thuộc về script `dev`, không bao giờ trong `start`. Trong production, runtime được triển khai sẽ tiêm `PORT`, `HOST` và các secret trực tiếp, và lệnh production là lệnh thuần túy (ví dụ: `bun run index.ts`). CLI `kazzle` không được cài đặt trong các image được triển khai, vì vậy một lệnh production gọi `kazzle run` sẽ gặp lỗi `kazzle: command not found`.

## `kazzle run` tiêm những gì

* các secret từ mục `env` của component trong `kazzle.config.ts`
* `PORT` và `HOST`
* URL của các component anh chị em như `KAZZLE_APP_COMPONENT_SERVER_URL`
* danh tính runtime của Kazzle như ID ứng dụng và tên component

## Ví dụ

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

`dev` chạy qua `kazzle run` để Kazzle có thể tiêm cổng xem trước và env runtime. `start` là lệnh thuần túy — production sẽ tự tiêm `PORT`/`HOST`/secrets.

Không đặt tên bộ sưu tập secret trong `package.json`. Đặt chúng trong `kazzle.config.ts`.

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

## Liên kết một checkout với một ứng dụng

`kazzle run` cần biết ứng dụng nào mà thư mục này thuộc về. Thứ tự phân giải:

1. `--app=<appId>` trên dòng lệnh
2. Biến env `KAZZLE_APP_ID` (được đặt tự động khi Kazzle khởi động một component được giám sát)
3. `.kazzle/link.json` được tìm kiếm từ thư mục hiện tại

Nếu không có cái nào được phân giải, `kazzle run` sẽ thoát với:

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

`app { create: {} }` sẽ tự động ghi `<checkout>/.kazzle/link.json` — giống như `.vercel/project.json` của Vercel. Tệp này là riêng cho mỗi bản sao và được gitignore. Sau khi `git clone` mới của một ứng dụng hiện có, hãy chạy:

```bash theme={"theme":"material-theme-darker"}
kazzle link              # khớp thư mục hiện tại với các checkout ứng dụng của space của bạn
kazzle link --app=<id>   # buộc một ứng dụng cụ thể
kazzle unlink            # xóa tệp liên kết
```

AI có thể sửa chữa một liên kết bị thiếu từ một thread với `app { link: { appId } }`.