CLI commands

create-rubrica creates, configures, publishes and updates Rubrica projects. It needs Node.js 20 or newer and git. Except for create, run the commands inside the project folder (or any subfolder).

Command	What it's for
npx create-rubrica@latest <pasta>	Creates the project
npx create-rubrica setup	Connects Convex, creates the admin and the initial data; turns on the integrations
npx create-rubrica config	Changes identity, appearance, layout or plugins after the project is created
npx create-rubrica publicar	Puts the site online on Vercel, and publishes again the next times
npx create-rubrica senha	Changes the panel password and unlocks a blocked login
npx create-rubrica@latest update	Brings in the new version of Rubrica without undoing your customizations
npx create-rubrica telemetria	Shows, turns on or turns off the project's anonymous telemetry

create

npx create-rubrica@latest meu-portfolio
# or
pnpm create rubrica meu-portfolio

The wizard downloads the latest version of the template and asks for the mode:

• Rápido (quick, the default): you pick the layout; colors, texture and fonts come matched to it.
• Personalizado (custom): you also pick the color scheme, light/dark mode, texture, fonts and language.

In both modes, it asks for:

• Layout: one of the 13 in the templates guide.
• What the site will have: a ready-made bundle ("Completo" (complete), "Para vender serviços" (to sell services), "Só o portfólio" (just the portfolio)) or the list of plugins to check one by one.
• Identity: your name, the site name, the address (without https://; if you don't have a domain yet, you can keep the suggested <projeto>.vercel.app), a sentence about what you do, your email and your X profile (optional).

In custom mode, it also asks for:

• Color scheme: one of the 15 schemes, with the one recommended for the layout marked.
• Color mode: light, dark or automatic (follows the visitor's system), and whether visitors can switch it.
• Texture: none, film grain, paper or scanlines.
• Fonts: main and mono.
• Language: Portuguese or English.

Then it starts git (main branch, with a first commit) and installs the dependencies: with pnpm if you ran pnpm create, with npm otherwise. Finally, it offers to set up the panel right away: if you accept, it connects the project to Convex and runs setup.

With the choices made on the site

In the Crie o seu (create yours) section of the Rubrica site, you build the look in the builder, fill in your details and copy a command with a recipe:

npx create-rubrica@latest ana-souza --receita eyJ2IjoxLCJsIjoiZGVza3RvcCIs...

The recipe carries the look, the plugins and the identity in a text with no spaces or accents, which works pasted into any terminal (bash, PowerShell, cmd). The CLI shows a summary, asks for confirmation and only asks for what's missing. Then it creates the project on Convex and runs setup, asking only for the panel password. Telegram and Vercel are left for a later setup.

If something in the recipe doesn't exist in this version of the CLI (a new layout, for example), it warns you and asks only about that.

Options

Options override the recipe.

Option	Values
--receita <código>	the code generated by the site
--layout <id>	cyberpunk, brutalist, swiss, bento, magazine, desktop, index, monograph, zine, blueprint, garden, chat, poster
--esquema <id>	one of the color schemes (neon, riso, sumi…)
--modo <modo>	claro, escuro or automatico
--alternancia / --sem-alternancia	shows or hides the button that lets visitors switch the mode
--textura <textura>	nenhuma, grao, papel or scanlines
--fonte <família> / --mono <família>	font name, with hyphens instead of spaces (--fonte instrument-sans)
--plugins <lista>	comma-separated ids (blog,portfolio), a bundle (recommended, freelancer, simple) or nenhum

Files that carry your choices

File	What it holds
rubrica.json	CLI state: source version, look, plugins, identity and, after publicar, the addresses of the live site. Commit it with the project: update and publicar depend on it.
rubrica.config.ts	Identity, SEO and RSS used in the build
src/index.css	The color scheme (light and dark) and the fonts
index.html	Meta tags, the fonts link and the look (color mode, switch and texture)
src/components/, src/pages/	The files of the chosen layout
convex/pluginRegistry.ts	The plugins turned on by default

setup

npx create-rubrica setup

Sets up the backend on Convex. If the project isn't connected to Convex yet (no .env.local), it connects on its own: it opens the login in the browser and creates the project. In a clone of a site that has already been published (rubrica.json has the production address), it doesn't create a new project: it asks you to pick the Convex project where the site lives.

Then it generates the login keys, saves the site address, creates the admin user and the initial data. The integrations only show up for the plugins that are on:

• Telegram and Vercel start with a yes-or-no question.
• OpenRouter (AI and translation) and Asaas (payments) ask for the key; Enter skips. With the Asaas key, it also generates the webhook token and shows the URL and the token to register in the Asaas dashboard.

You can run it again whenever you want: the existing admin is kept and the initial data only creates what's missing.

config

npx create-rubrica config

Changes the choices made in create:

• Identity: the questions come filled in with what's saved; it updates rubrica.config.ts, the meta tags in index.html and rubrica.json.
• Appearance: color scheme, light/dark mode, switch, texture and fonts.
• Layout: changes the layout. Careful: it overwrites the layout files, and any customizations in them are lost.
• Plugins: which ones are on by default.

publicar

npx create-rubrica publicar

Puts the site online on Vercel. The first time, it creates the project on Vercel, prepares the production database, creates the admin of the published site and turns on the panel's Publicar (publish) button. After that, running it again just publishes. The step by step is in Publishing the site.

senha

npx create-rubrica senha

For when you forgot the panel password or got locked out by wrong attempts (the lock is also cleared). It asks whether the change is on the published site or on the one on your computer, the email and the new password: 12 or more characters, with uppercase, lowercase and a number.

It only works with access to the Convex project, that is, for the owner, in the project folder and logged in to Convex.

update

npx create-rubrica@latest update --dry-run   # shows what would change
npx create-rubrica@latest update             # applies it

Updates the project to the latest version without undoing your customizations. The CLI compares, file by file, the version the project came from, the new version and your project:

• a file you didn't touch gets the new version;
• a file you changed and Rubrica didn't change stays as it is;
• when both changed different parts, the changes are merged;
• when both changed the same part, your file stays intact and the new version is saved next to it as <arquivo>.rubrica-new.

.env*, rubrica.json and the data generated in the build (public/data/, RSS, sitemap) are never touched.

Option	What it's for
--dry-run	Only shows the plan
--to <versão>	Updates to a specific version
--from <versão>	Version the project was created with (projects created up to v0.3.18 always wrote 0.1.0)
--yes	Applies without asking

Full guide: Updating your Rubrica.

telemetria

npx create-rubrica telemetria            # shows whether it's on
npx create-rubrica telemetria desligar   # turns it off for this project
npx create-rubrica telemetria ligar      # turns it back on

The CLI sends, with no personal data, the choices made in the commands (layout, colors, plugins) so Rubrica knows what's used the most. The choice is stored in rubrica.json. For a single run, use --sem-telemetria on any command. What is and isn't sent: CLI telemetry.

Environment variables

Variable	What it's for
RUBRICA_VERCEL_GLOBAL_CONFIG	Picks the Vercel account when there's more than one on the computer: the account's config folder (it's the Vercel CLI's --global-config).
RUBRICA_TELEMETRIA	0 turns telemetry off on any command.
DO_NOT_TRACK	1 turns telemetry off, as in other terminal tools.

With an AI agent

The project ships with an AGENTS.md (and a CLAUDE.md for Claude Code) that teaches agents such as Claude Code, Codex and Cursor how to use the CLI: what they can run on their own (update --dry-run and, once you say ok, update --yes), what you run in your own terminal (setup, config, publicar, senha) and the step-by-step for updating Rubrica, including the .rubrica-new files. Ask "update Rubrica" and the agent follows that script.