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

> Execute comandos de app gerados com contexto de runtime do Kazzle.

# Kazzle CLI

Use a Kazzle CLI para executar comandos de app **em desenvolvimento e preview**:

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

Tudo após `--` é o comando real. Kazzle injeta o ambiente de runtime primeiro.

`kazzle run` é apenas para desenvolvimento e preview. Pertence ao script `dev`, nunca em `start`. Em produção, o runtime implantado injeta `PORT`, `HOST` e secrets diretamente, e o comando de produção é o comando simples (ex: `bun run index.ts`). A CLI `kazzle` não é instalada em imagens implantadas, então um comando de produção que chama `kazzle run` falha com `kazzle: command not found`.

## O que `kazzle run` injeta

* secrets da entrada `env` do componente em `kazzle.config.ts`
* `PORT` e `HOST`
* URLs de componentes irmãos como `KAZZLE_APP_COMPONENT_SERVER_URL`
* identidade de runtime do Kazzle, como ID do app e nome do componente

## Exemplo

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

`dev` executa através de `kazzle run` para que Kazzle possa injetar a porta de preview e env de runtime. `start` é o comando simples — produção injeta `PORT`/`HOST`/secrets por si mesma.

Não coloque nomes de coleções de secrets em `package.json`. Coloque-os em `kazzle.config.ts`.

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

## Vinculando um checkout a um app

`kazzle run` precisa saber a qual app este diretório pertence. Ordem de resolução:

1. `--app=<appId>` na linha de comando
2. variável de env `KAZZLE_APP_ID` (definida automaticamente quando Kazzle inicia um componente supervisionado)
3. `.kazzle/link.json` procurado a partir do diretório atual

Se nenhum desses resolver, `kazzle run` sai com:

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

`app { create: {} }` escreve `<checkout>/.kazzle/link.json` automaticamente — como `.vercel/project.json` do Vercel. O arquivo é por clone e gitignored. Após um `git clone` recente de um app existente, execute:

```bash theme={"theme":"material-theme-darker"}
kazzle link              # corresponder o diretório atual aos checkouts de app do seu Space
kazzle link --app=<id>   # forçar um app específico
kazzle unlink            # deletar o arquivo de link
```

A IA pode reparar um link ausente de uma thread com `app { link: { appId } }`.