> ## 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`
* `KAZZLE_APP_COMPONENT_SERVER_URL` 같은 형제 컴포넌트 URL
* 앱 ID 및 컴포넌트 이름 같은 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`처럼. 파일은 클론별이며 gitignored입니다. 기존 앱의 새로운 `git clone` 후에 다음을 실행하세요:

```bash theme={"theme":"material-theme-darker"}
kazzle link              # 현재 디렉토리를 Space의 앱 체크아웃과 일치시킵니다
kazzle link --app=<id>   # 특정 앱을 강제합니다
kazzle unlink            # 링크 파일을 삭제합니다
```

AI는 스레드에서 `app { link: { appId } }`로 누락된 링크를 복구할 수 있습니다.