> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Comandos da CLI

> Referência — init, dev, auth, validate, check, mcp, build, sync, pull, pack e publish.

Todos os exemplos assumem que você está **dentro da pasta do seu tema** (`cd minha-loja`).

***

## `corvex init`

Cria um tema Corvex a partir do scaffold oficial.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex init . --name "Minha Loja" --slug minha-loja
```

O scaffold inclui `package.json` com `"dev": "corvex dev"`.

***

## `corvex dev`

Servidor oficial de desenvolvimento do tema (preview local + hot reload).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm run dev
# ou
corvex dev .
corvex dev . --port 5180 --open
corvex dev . --host 0.0.0.0
corvex dev . --live-reload full-page
corvex dev . --ignore "**/*.md" --only "sections/**"
corvex auth && corvex link && corvex dev . --store
```

| Flag | Default | Efeito |
| - | - | - |
| `--port` | `5173` | Porta HTTP (se ocupada, tenta a próxima; com `--port` fixo falha se ocupada) |
| `--host` | `127.0.0.1` | Bind local. Rede só com host explícito (`0.0.0.0`) |
| `--open` | off | Abre o navegador na URL do preview |
| `--live-reload` | `hot-reload` | `hot-reload` (CSS hot + remount JSX), `full-page` ou `off` |
| `--ignore`, `-x` | — | Glob ignorado no watch (repetível) |
| `--only`, `-o` | — | Restringe o watch a globs (repetível) |
| `--store`, `-s` | off (mock) | Modo conectado: API pública da loja (exige `corvex auth`). Sem valor usa `corvex link` / `CORVEX_DEV_STORE_ID` |
| `--verbose` | off | Loga eventos de watch/HMR |
| `--notify` | — | Atualiza o arquivo (mtime) após cada build ok |

**O que faz**

* Detecta a raiz do tema (`theme.json`) e valida o essencial
* Compila com o mesmo pipeline de `corvex build` (`buildThemeBundleV2`)
* Serve o tema real (templates, layout groups, seções, blocos, snippets, settings, assets)
* **Padrão:** mock determinístico em `/api/corvex-api` (sem auth, sem loja real)
* **Com `--store`:** preview com catálogo da loja vinculada (via Theme SDK); imprime URL do Editor quando há vínculo
* CSS: hot swap; JSX/estrutura: remonta o preview; schema/templates/`theme.json`: reload completo (modo `hot-reload`)
* Overlay de erros (compile / validate / runtime)
* Ctrl+C encerra watchers e o servidor

**Rotas de preview** (contrato de vitrine): `/`, `/products/:handle`, `/collections/:handle`, `/search`, `/cart`, `/blogs/...`, `/pages/:handle`.

**Não faz:** sync bidirecional editor↔arquivos no `dev`, preview compartilhável por túnel, overwrite automático. Use `corvex pull` / `corvex sync` com modo explícito.

Sem `--store` não exige `corvex auth`, `corvex link` nem `corvex sync`.

***

## `corvex auth` · `corvex link`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex auth
corvex link
corvex whoami
```

Autenticação e vínculo com loja — pré-requisito para `sync` e instalação no Editor.

***

## `corvex validate`

Valida manifest, schemas, templates obrigatórios e bundle.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex validate .
```

**Verifica:**

* `theme.json` (`manifestVersion: 2`, `slug`, `sections`, `templates`)
* `config/settings.schema.json`
* `templates/index`, `product`, `collection`, `cart`, `search`
* Cada section em `theme.json` tem `section.jsx` + `schema.json`
* Grava `schema.identity.json` (`name` atual + nomes já vistos). Rename de `name` é permitido. Commite o lockfile. Ver [identidade](https://docs-loja.usecorvex.com.br/reference/contracts/section.md#identidade-type-estável-name-livre).

O bundle não é pré-requisito. Dá para validar antes do build. Falta de `screenshots/desktop` e `screenshots/mobile` gera aviso e não reprova. A linha de sucesso é `Tema válido: {slug}@{version}`.

***

## `corvex check`

Theme Check — análise ampliada (reutiliza o validate + regras de SDK, JSX, a11y estática e performance).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex check .
corvex check . --json
corvex check . --list
```

Detalhes, regras e CI: [Theme Check](https://docs-loja.usecorvex.com.br/cli/theme-check.md).

***

## `corvex mcp`

Servidor MCP oficial (stdio) para agentes: contratos, validate, check, build e Dev Server local.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex mcp
corvex mcp doctor
corvex mcp setup --cursor
```

Detalhes e segurança: [MCP Server](https://docs-loja.usecorvex.com.br/cli/mcp.md).

***

## `corvex build`

Compila sections, snippets e assets do tema.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex build .
```

**Saída confirmada no starter:**

* `.corvex/theme.js` — bundle do tema
* `.corvex/locales.json` — quando o tema tem `locales/`

A mensagem é `Bundle compilado:` seguida do caminho de `.corvex/theme.js`.

**Anexa no bundle (não importe esses JSON no JSX nem declare propriedade estática no componente):**

* `schema.json` de cada section → schema e defaults do inspector (CLI ≥ 2.3.3)
* `blocks.json` de cada section → lista de blocks do inspector (CLI ≥ 2.3.4)
* `schema.json` de cada block → schema do block (CLI ≥ 2.3.5)

Use `@corvex/theme-cli` **2.3.5+**. Sem o attach do schema do block, o item no inspector aparece sem configurações.

***

## `corvex sync`

Build + publica versão **PRIVATE** na loja vinculada.

Por padrão, em terminal interativo, a CLI **pergunta** o que deve ser atualizado na loja. Use flags para pular o menu ou forçar um modo específico.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex sync .
corvex sync . --open              # abre o Editor após sync
corvex sync . --keep-content      # só código — preserva editor
corvex sync . --with-templates    # código + templates do pacote local
corvex sync . --full              # instalação nova (reset)
corvex sync . -y                  # sem prompt (modo "só código")
```

### O que cada modo faz

| Modo | Flag | Código (JS/CSS/seções) | Templates / conteúdo do editor |
| - | - | - | - |
| **Só código** | `--keep-content` / `--content code` | Atualiza bundle na instalação atual | **Preservado** — textos, imagens, ordem de sections |
| **Código + templates** | `--with-templates` / `--content templates` | Atualiza bundle | Reaplica `default-templates.json` do tema local |
| **Instalação completa** | `--full` / `--content full` | Nova instalação na loja | Templates e settings padrão do pacote |

### Quando usar cada modo

**Só código** (recomendado no dia a dia de dev):

* Você alterou CSS, JS ou markup de uma section
* O merchant já personalizou textos, imagens e layout no Editor
* Você quer ver o código novo **sem** apagar o trabalho do painel

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex sync . --keep-content --open
```

**Código + templates**:

* Você mudou a estrutura padrão das páginas no repositório (`templates/*.json`)
* Quer que a loja receba esses layouts padrão (sobrescreve o rascunho das páginas no Editor)

**Instalação completa**:

* Primeira instalação ou reset total
* Quer descartar personalizações e voltar ao estado padrão do tema

### Comportamento técnico

1. `corvex build` — compila o bundle
2. `POST /stores/storefront/catalog/themes/publish` — nova versão PRIVATE no catálogo
3. Na loja:
   * **Só código / templates**: `PATCH .../themes/:storeThemeId/version` na instalação existente (`lastStoreThemeId` em `corvex.theme.json`)
   * **Full**: `POST .../themes/install` — nova instalação
4. Se modo **templates**: reaplica `draftDocument` de cada template a partir do pacote local
5. Salva metadados em `corvex.theme.json`

### Flags de conteúdo

| Flag | Alias | Modo |
| - | - | - |
| `--keep-content` | `--code-only` | `code` |
| `--with-templates` | `--reset-templates` | `templates` |
| `--full` | `--reset-content` | `full` |
| `--content <modo>` | — | `code`, `templates` ou `full` |
| `-y` / `--yes` | — | Pula o menu; usa modo **só código** |

***

## `corvex pull`

Baixa arquivos do tema para a pasta local. Há **dois modos**:

| Modo | Comando | Origem dos dados |
| - | - | - |
| **Loja (padrão)** | `corvex pull .` | Instalação atual na loja (inclui edições do Editor) |
| **Catálogo** | `corvex pull . --version 1.0.130` | Source archive da versão publicada no marketplace |

### Pull da loja (padrão)

Inverso do `sync`. Útil quando o merchant personalizou a loja no Editor e você quer o mesmo código + templates + settings na pasta local.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex pull .
corvex pull . --force           # sobrescreve arquivos locais
corvex pull . --zip              # gera .cvex-theme.zip após o download
corvex pull . --out ./backup     # salva em outra pasta
corvex pull . --no-refresh       # só baixa o que já está no servidor
```

**Inclui:**

* Código-fonte do tema (sections, layout, schemas)
* `config/settings.data.json` — settings atuais da loja
* `templates/*.json` — composição das páginas (rascunho do Editor)

**Pré-requisito:** a loja precisa ter **source archive** no catálogo (rode `corvex sync` pelo menos uma vez). Sem isso, o servidor não monta o snapshot para download.

### Pull de versão do catálogo (`--version`)

Baixa o **código-fonte publicado** em uma versão específica do tema (o zip enviado no `corvex publish` / `corvex sync`), **sem** templates/settings editados no Editor depois.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex pull . --version 1.0.130
corvex pull . --version v1.1.0 --force
corvex pull . --version <themeVersionId> --slug meu-tema
```

| Flag | Descrição |
| - | - |
| `--version` | Semver (`1.0.130`, `v1.1.0`) ou UUID da `themeVersionId` |
| `--slug` | Slug do tema no catálogo (opcional se `theme.json` ou `corvex.theme.json` já têm o slug) |
| `--force` | Sobrescreve arquivos locais existentes |
| `--zip` | Gera `.cvex-theme.zip` após o download |
| `--out` | Pasta de destino |

O slug é resolvido nesta ordem: `--slug` → `corvex.theme.json` → `catalogSlug` → `theme.json` → `slug`.

**Não exige** loja vinculada — só autenticação (`corvex auth`). A versão precisa ter sido publicada com source archive (comportamento padrão do `publish`/`sync` desde v2.2+).

### Fluxos típicos

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Estado atual da loja (com edições do Editor)
corvex auth
corvex link . --store <uuid-da-loja>
corvex pull . --force

# Voltar ao código de uma versão publicada
corvex auth
corvex pull . --version 1.0.130 --force

corvex build
corvex pack .
```

***

## `corvex pack`

Gera ZIP distribuível do tema.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex pack .
corvex pack . --out dist/meu-tema-1.0.0.zip
```

***

## `corvex publish`

Publica uma versão do tema no **catálogo Corvex** (código do tema — não é o “Publicar” do merchant no Editor).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex publish . --visibility PRIVATE
corvex publish . --update --visibility PUBLIC --bump minor
```

### Flags comuns

| Flag | Valores | Descrição |
| - | - | - |
| `--visibility` | `PRIVATE`, `PUBLIC` | Visibilidade no catálogo |
| `--update` | — | Nova versão do mesmo `slug` |
| `--bump` | `patch`, `minor`, `major` | Incremento de versão |
| `--install` | — | Instala na loja vinculada após publish |

### Resposta

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "definition": { "slug": "meu-tema" },
  "version": { "id": "uuid-theme-version", "version": "1.0.0" }
}
```

Guarde **`version.id`** (`themeVersionId`) para instalação.

***

## `corvex skills`

Skills de tema empacotadas na CLI. Não baixam da rede. A versão instalada é a compatível com `manifestVersion`, não necessariamente a maior que existir no futuro.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex skills install .
corvex skills update . --yes
corvex skills status .
corvex skills list .
corvex skills doctor .
corvex skills disable .
```

`install` não substitui arquivo editado por você e não apaga skill de terceiro. `update` sem `--yes` não grava. `--force` só tem efeito junto com `--yes`.

Guia: [Agent Skills](https://docs-loja.usecorvex.com.br/guides/agent-skills.md).

***

## `corvex --help`

Lista comandos e opções atualizadas da sua instalação.

***

## Separação importante

| Ação | Ferramenta | O que publica |
| - | - | - |
| Código do tema | `corvex publish` | Versão no catálogo |
| Layout da loja | Editor → **Publicar** | Conteúdo do merchant |

Ver [Publish Contract](https://docs-loja.usecorvex.com.br/reference/contracts/publish.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.