Kazzle CLI

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

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

{
  "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.

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:

--app=<appId> on the command line
KAZZLE_APP_ID env var (set automatically when Kazzle starts a supervised component)
.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:

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 }.

​Kazzle CLI

​What kazzle run injects

​Example

​Linking a checkout to an app

Kazzle CLI

What `kazzle run` injects

Example

Linking a checkout to an app