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

# CLI corvex

> Ferramenta oficial para validar, compilar, sincronizar e publicar Themes Corvex.

Pacote npm público: **`@corvex/theme-cli`**

A CLI é a interface oficial para desenvolvimento de Themes. Você não precisa do repositório interno da Corvex — apenas Node.js, a CLI e acesso a uma loja.

***

## Instalação

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install -g @corvex/theme-cli
corvex --version
```

Requer Node.js **>= 18**.

***

## Fluxo típico (local)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex init meu-tema --name "Meu Tema" --slug meu-tema
cd meu-tema
npm install
npm run dev                 # = corvex dev — preview local com hot reload
```

Abra a URL impressa no terminal (padrão `http://127.0.0.1:5173`). Mock público por padrão; opcional `corvex auth && corvex link && corvex dev --store` para dados da loja no mesmo servidor.

## Fluxo com loja / catálogo

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex auth
corvex link
corvex validate .
corvex sync --open          # compila + instala + abre Editor
corvex publish . --update   # nova versão no catálogo
```

| Etapa | Comando | O que faz |
| - | - | - |
| Scaffold | `corvex init` | Cria estrutura atual oficial e instala Agent Skills |
| Sem skills | `corvex init --no-skills` | Scaffold sem Agent Skills |
| Preview local | `corvex dev` / `npm run dev` | Servidor local + HMR + mock público |
| Preview + loja | `corvex dev --store` | Mesmo servidor; proxy API pública (exige `auth`) |
| Login | `corvex auth` | Autentica na sua conta Corvex |
| Loja | `corvex link` | Vincula pasta → loja de dev |
| QA | `corvex validate` | Valida manifest, schemas, templates |
| Qualidade | `corvex check` | Theme Check (validate + SDK/JSX/a11y/perf) |
| Agentes | `corvex mcp` | Servidor MCP local (stdio) |
| Build | `corvex build` | Gera bundle do tema |
| Dev loop remoto | `corvex sync` | Build + publica na loja (preserva conteúdo do editor se pedir) |
| Backup local | `corvex pull` | Baixa templates/settings/código da loja para a pasta |
| Versão antiga | `corvex pull --version` | Baixa código-fonte de uma versão publicada no catálogo |
| Catálogo | `corvex publish` | Publica versão no marketplace |

Libs npm (carrossel, animação, etc.): instale na raiz do tema com `npm install`, depois `corvex build`. Guia: [Bibliotecas de terceiros](https://docs-loja.usecorvex.com.br/guides/third-party-libraries.md).

***

## Autenticação

| Comando | Descrição |
| - | - |
| `corvex auth` | Login interativo |
| `corvex auth --token <api-key>` | Login com API key (`cvx_live_...`) |
| `corvex whoami` | Sessão atual |
| `corvex logout` | Remove credenciais locais |

Credenciais ficam em `~/.corvex/credentials.json` (ou keychain do sistema).

Não é necessário configurar tokens manualmente se você usa `corvex auth`.

***

## Loja vinculada

| Comando | Descrição |
| - | - |
| `corvex link` | Escolhe loja → grava `corvex.theme.json` |
| `corvex link --store <uuid>` | Vincula loja específica |
| `corvex link --status` | Mostra vínculo atual |
| `corvex link --unlink` | Remove vínculo |

***

## Variáveis de ambiente (opcional)

Usadas apenas se você **não** usa `corvex auth` / `corvex link`:

| Variável | Default produção | Uso |
| - | - | - |
| `CORVEX_API_URL` | (padrão da CLI) | Override opcional da API usada por auth/sync |
| `CORVEX_APP_URL` | `https://builder.usecorvex.com.br` | URL do Editor |
| `CORVEX_ACCESS_TOKEN` | — | Token alternativo ao `corvex auth` |
| `CORVEX_DEV_STORE_ID` | — | Loja fixa (pula `corvex link`) |

Developers externos devem preferir `corvex auth` em vez de variáveis manuais.

***

## Arquivos gerados pela CLI

| Arquivo | Descrição |
| - | - |
| `corvex.theme.json` | Loja vinculada (`corvex link`) |
| `.corvex/theme.js` | Bundle compilado (`corvex build`) |
| `.corvex/theme.css` | CSS agregado do tema |

**Não versione** `.corvex/` no git.

***

## Sync sem perder o editor

Ao rodar `corvex sync`, escolha **só código** para atualizar JS/CSS/seções sem apagar textos e imagens que o merchant editou no painel:

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

Modos completos, flags e `corvex pull`: [Comandos da CLI](https://docs-loja.usecorvex.com.br/cli/commands.md).

***

## Referência completa

[Comandos da CLI](https://docs-loja.usecorvex.com.br/cli/commands.md)


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