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

> Run generated app commands with Kazzle runtime context.

# Kazzle CLI

Use the Kazzle CLI to run app commands **in development and preview**:

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

Everything after `--` is the real command. Kazzle injects the runtime environment first.

`kazzle run` is for development and preview only. It belongs in the `dev` script, never in `start`. In production, the deployed runtime injects `PORT`, `HOST`, and secrets directly, and the production command is the bare command (e.g. `bun run index.ts`). The `kazzle` CLI is not installed in deployed images, so a production command that calls `kazzle run` crashes with `kazzle: command not found`.

## What `kazzle run` injects

* secrets from the component's `env` entry in `kazzle.config.ts`
* `PORT` and `HOST`
* sibling component URLs like `KAZZLE_APP_COMPONENT_SERVER_URL`
* Kazzle runtime identity such as app ID and component name

## Example

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

`dev` runs through `kazzle run` so Kazzle can inject the preview port and runtime env. `start` is the bare command — production injects `PORT`/`HOST`/secrets itself.

Do not put secret collection names in `package.json`. Put them in `kazzle.config.ts`.

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

## Linking a checkout to an app

`kazzle run` needs to know which app this directory belongs to. Resolution order:

1. `--app=<appId>` on the command line
2. `KAZZLE_APP_ID` env var (set automatically when Kazzle starts a supervised component)
3. `.kazzle/link.json` walked up from the current directory

If none of those resolve, `kazzle run` exits with:

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

`app { action: "create" }` writes `<checkout>/.kazzle/link.json` automatically — like Vercel's `.vercel/project.json`. The file is per-clone and gitignored. After a fresh `git clone` of an existing app, run:

```bash theme={"theme":"material-theme-darker"}
kazzle link              # match the current directory against your space's app checkouts
kazzle link --app=<id>   # force a specific app
kazzle unlink            # delete the link file
```

The AI can repair a missing link from a thread with `app { action: "link", appId }`.