Documentação
Comandos do CLI
O create-rubrica cria, configura, publica, atualiza e migra o site. Dentro de um projeto, o mesmo CLI responde por rubrica: npx rubrica <comando> é igual a npx create-rubrica <comando>. Precisa de Node 22.23 ou mais novo e do git.
npx create-rubrica@latest <comando> [opções]
npx create-rubrica --help # lista os comandos
npx create-rubrica --version
Rode os comandos na pasta do projeto (menos o create). Quando um comando precisa de uma resposta e não há terminal interativo, use as opções ou --yes. Em qualquer comando, --sem-telemetria desliga a telemetria só naquela execução.
| Comando | Para quê |
|---|---|
create |
Cria um site novo |
setup |
Liga o Convex, cria o login e o conteúdo inicial |
config |
Muda identidade, tipo, tema, cores, idiomas, plugins ou analytics |
publicar |
Põe o site no ar na Vercel |
senha |
Troca a senha do painel |
update |
Atualiza o núcleo e o tema |
ejetar |
Copia o componente de um bloco para o projeto |
verificar |
Confere o projeto (o pnpm test) |
testar-tema |
Bateria de testes de um tema |
mcp |
Servidor MCP local para agentes |
migrar |
Leva um projeto da v1 para a v2 |
telemetria |
Mostra, liga ou desliga a telemetria |
create
npx create-rubrica@latest [create] <pasta> [opções]
Gera o projeto: @rubrica/core e o tema, astro.config.ts, o convex/ de reexportações, os arquivos de hospedagem (vercel.json, public/_redirects, public/_headers), o AGENTS.md e o .mcp.json. Instala as dependências, inicia o git e oferece rodar o setup. A pasta precisa estar vazia ou não existir. Sem opções, pergunta o que falta.
| Opção | Valor |
|---|---|
--tipo |
pessoal (padrão) ou empresa |
--tema <id> |
padrao, cyberpunk, brutalist, swiss, bento, magazine, desktop, index, monograph, zine, blueprint, garden, chat ou poster |
--nome <texto> |
Nome do site ou da empresa |
--url <endereço> |
Endereço do site (meusite.com) |
--descricao <texto> |
Descrição curta (SEO) |
--autor <nome> |
Dono do site (pessoal) ou contato (empresa) |
--email <e-mail> |
E-mail do login do painel e de contato |
--idiomas <lista> |
Idiomas separados por vírgula (padrão pt-BR) |
--idioma-principal <código> |
Idioma sem prefixo na URL (padrão: o primeiro) |
--esquema <id> |
Esquema de cores (veja Temas) |
--modo |
escuro, claro ou automatico |
--plugins <lista> |
Plugins separados por vírgula, ou um pacote: recommended, freelancer ou simple (os dois últimos só no tipo pessoal) |
--gerenciador |
pnpm ou npm (padrão: o que rodou o comando) |
--local <pasta> |
Usa os pacotes de um clone do monorepo (link:), para testar versões não publicadas |
--sem-instalar |
Não instala as dependências |
--sem-git |
Não roda o git init |
--sem-setup |
Não oferece o setup no fim |
-y, --yes |
Não pergunta nada: usa as opções e os padrões |
setup
npx create-rubrica setup
Interativo; quem roda é você, porque pede a senha e as chaves. Liga o projeto ao Convex de desenvolvimento, grava as chaves de login e as variáveis do backend, cria o usuário root (a senha é digitada ali, nunca passa por um agente), monta o conteúdo inicial pela receita do tema e pergunta as integrações (Telegram, e-mail, OpenRouter, Asaas, deploy hook). É seguro rodar de novo: ele só completa o que falta.
config
npx create-rubrica config [opções]
Sem opções e num terminal, pergunta o que mudar. Com opções, muda direto:
| Opção | O que muda |
|---|---|
--nome, --url, --descricao, --autor, --email |
Identidade |
--tipo pessoal|empresa |
Tipo do site (as páginas existentes ficam; blocos exclusivos do outro tipo deixam de aparecer) |
--tema <id> |
Tema (troca o pacote, instala e atualiza o astro.config.ts) |
--esquema <id>, --modo escuro|claro|automatico |
Cores |
--idiomas <lista>, --idioma-principal <código> |
Idiomas (Idiomas) |
--plugins <lista> |
Liga e desliga plugins: +blog,-resume. Sem sinal, liga |
--analytics <script>, --analytics-id <id> |
Liga o Umami e libera a origem na CSP. --analytics desligar desliga |
--producao |
Grava também no Convex de produção (pede confirmação) |
--sem-instalar |
Não roda a instalação ao trocar de tema |
-y, --yes |
Não pergunta |
As mudanças vão para o rubrica.json, para o código (quando precisa) e para o Convex de desenvolvimento. O site publicado só muda com --producao e um novo publicar.
publicar
npx create-rubrica publicar
Quem roda é você, a pedido seu: publica em produção. Na primeira vez, cria o projeto na Vercel e o banco de produção; depois, só publica de novo. Passo a passo em Publicar o site.
senha
npx create-rubrica senha
Troca a senha do painel (esqueceu, ou o login ficou bloqueado). Pergunta se é no site publicado ou no do computador. Sempre você roda: a senha nunca passa por um agente.
update
npx create-rubrica@latest update [--dry-run] [--yes] [--para <versão>] [--forcar]
| Opção | O que faz |
|---|---|
--dry-run |
Mostra o plano sem gravar nada |
-y, --yes |
Aplica sem pedir confirmação |
--para <versão> |
Atualiza para uma versão específica do núcleo |
--forcar |
Segue mesmo com mudanças sem commit no git |
Sobe @rubrica/core e o tema, regenera o convex/, roda no desenvolvimento as migrações de dados da versão e avisa dos componentes ejetados cujo original mudou. Veja Atualizar o Rubrica.
ejetar
npx create-rubrica ejetar <bloco> [--forcar]
npx create-rubrica ejetar --listar
Copia o componente do bloco (do tema, ou do núcleo) para src/overrides/ e passa a usar a cópia. --forcar copia de novo por cima; --listar mostra o que já foi ejetado e se o original mudou. Sem argumento, lista os blocos disponíveis.
verificar
npx create-rubrica verificar
É o pnpm test do projeto. Confere se o convex/ gerado bate com o núcleo instalado, se o tema do rubrica.json está instalado e no astro.config.ts, se os marcadores rubrica: do astro.config.ts estão no lugar e se os ejetados existem. Termina com erro se algo estiver fora.
testar-tema
npx create-rubrica testar-tema [tema] [opções]
A bateria de testes de tema (@rubrica/theme-tester): axe, SEO, JavaScript por página e Lighthouse, sobre os sites de demonstração. No monorepo: pnpm testar-tema <tema>.
| Opção | O que faz |
|---|---|
--todos |
Todos os temas de packages/themes/* |
--listar |
Lista os temas do monorepo |
--site pessoal|empresa |
Testa só um tipo de site |
--sem-lighthouse |
Pula o Lighthouse |
--so-lighthouse |
Roda só o Lighthouse |
--js-kb <n> |
Limite de JavaScript (gzip) por página com ilha (padrão 120) |
--lh-performance <n>, --lh-acessibilidade <n>, --lh-seo <n> |
Notas mínimas (padrão 90, 95 e 95) |
--lh-execucoes <n> |
Máximo de execuções do Lighthouse por página (padrão 3) |
--json <arquivo> |
Grava o relatório em JSON |
--verbose |
Mostra também as verificações que passaram |
--manter-dist |
Não apaga a pasta do build |
--raiz <pasta> |
Raiz do monorepo |
Saída: 0 se tudo passou, 1 se algo falhou, 2 para erro de uso.
mcp
npx rubrica mcp # inicia o servidor (o .mcp.json faz isso)
npx rubrica mcp login # login no terminal (também: --email, --producao, --senha-stdin)
npx rubrica mcp whoami # projeto, banco, conta e papel
npx rubrica mcp logout
npx rubrica mcp --producao # servidor apontando para o Convex de produção
Veja Agentes de IA. Sem banner: o stdout é o protocolo.
migrar
npx create-rubrica@latest migrar [--export <zip>] [--yes]
npx create-rubrica@latest migrar --relatorio [--export <zip>] [--saida <arquivo>]
npx create-rubrica@latest migrar dados --export <zip> [--saida <pasta>]
npx create-rubrica@latest migrar conferir --v1 <url|pasta> [--v2 <pasta dist>]
| Forma | O que faz |
|---|---|
migrar |
Cria a branch rubrica-v2, troca o código, converte os dados (com --export), builda e grava o relatório |
migrar --relatorio |
Só mostra: tema, personalizações e (com --export) o que os dados viram. Não grava nada |
migrar dados |
Só a conversão dos dados (arquivo de import, pendentes, fixtures e relatório) |
migrar conferir |
Compara título, h1 e texto das páginas principais entre a v1 e a v2 |
Outras opções: --template-v1 <pasta> (usa um clone do repositório como v1 de referência, sem internet), --convex-url <endereço> (endereço das imagens do Convex), --local <pasta> (pacotes do monorepo), --sem-instalar e --sem-build. Passo a passo em Migrar da v1. O comando não grava no Convex.
telemetria
npx create-rubrica telemetria [ligar|desligar]
Sem argumento, mostra se está ligada e por quê. Veja Telemetria.