CLI

A CLI do Fayz scaffolda projetos, valida manifestos e limites de arquitetura, assiste a migração de config-em-código para manifesto, e provisiona o banco Supabase de um app a partir dos pacotes instalados. Você a chama sem instalar nada, via npx:

npx @fayz-ai/cli <comando>

Comandos

O create recebe o kind e um nome em kebab-case (^[a-z0-9][a-z0-9-]*$) — sem flags. Ele gera um projeto Vite com app.manifest.json, src/plugins.generated.ts, src/registry.tsx, AGENTS.md e o .env.example. Veja o tutorial 01.

fayz create plugin

Cria um plugin app-local em src/plugins/<nome>/, seguindo o mesmo contrato dos plugins oficiais (index/data/schema/README). Detalhes em Incubator.

fayz doctor

Valida o app do diretório atual: estrutura do manifesto, plugins referenciados, cobertura de locale e os limites de arquitetura (imports de provedor + superfície suportada). Problemas estruturais do manifesto saem com erro (exit 1); problemas de boundary são avisos (soft enforcement). Um app sem app.manifest.json mas com package.json é tratado como código-primeiro — roda só os boundaries e passa. Veja Testar e debugar.

fayz db apply

Monta a ordem de migração — o core primeiro, depois os módulos versionados de cada plugin, depois os incubator — a partir dos pacotes instalados e a aplica no seu projeto Supabase via Management API. O CLI atual rotula os passos como spine → drizzle → seed → plugins → incubator (os três primeiros são o core; o rótulo migra na wave de industry pools).

Flags

Env (obrigatório num apply real; nunca no --dry-run)

O comando lê primeiro do ambiente do processo, depois de <app>/.env.local, depois de <app>/.env — e os arquivos nunca sobrescrevem o ambiente. Sem essas variáveis, um apply real para com um erro claro; o --dry-run não precisa delas.

# planeje sem tocar no banco
npx @fayz-ai/cli db apply --dry-run

# aplique (pede confirmação; use --yes em CI)
npx @fayz-ai/cli db apply

O fluxo completo de conexão está em Supabase.

fayz extract

Assiste a migração de um app código-primeiro (config em src/App.tsx / defineSaas) para o app.manifest.json. Rode-o na raiz de um app existente; ele lê o código de config e propõe o manifesto equivalente.

fayz db pool e fayz db fan-out (industry pools — Runner v2) Beta

Enquanto o db apply provisiona um projeto Supabase, o Runner v2 opera sobre uma frota de industry pools — os projetos Supabase compartilhados por vertical. Ele lê o registro de pools de cli/pools.config.json (use --pools-file para apontar outro arquivo) e pega o token de SUPABASE_PAT / SUPABASE_ACCESS_TOKEN (a ref de cada pool vem do arquivo de pools, não do ambiente).

Applies são sempre ledger-gated

Toda aplicação passa pelo ledger de cada pool. Um arquivo já aplicado, sem mudança, é pulado. Um arquivo já aplicado cujo checksum mudou é um HARD STOP — o runner para em vez de reaplicar. A regra é absoluta: nunca edite uma migração já aplicada; escreva a próxima. Isso garante que o histórico de cada pool seja reprodutível e auditável.

Fan-out: canary primeiro

O db fan-out não aplica em tudo de uma vez. Ele aplica primeiro no pool marcado como canary (--canary <pool> para forçar outro), e só depois nos demais — para um erro aparecer num pool antes de tocar a frota inteira. Pools em estado PROVISIONING são pulados no fan-out a menos que nomeados explicitamente; um pool marcado dataCritical exige --allow-critical (junto de --yes).

move-tenant é seguro por construção

O move-tenant é dry-run por padrão — sem --yes ele só mostra o plano. Com --yes, ele: faz backup em JSON antes de qualquer escrita, insere os registros no destino (parents-first), verifica as contagens (se divergirem, é HARD STOP e a origem fica intacta) e só então apaga na origem (children-first). O pool de destino não pode estar em PROVISIONING.

fayz login / fayz logout / fayz deploy Experimental

Esse trio publica um app direto na plataforma Fayz, sem CI próprio.

• fayz login [--token <fayz_...> | --status] — salva o token de acesso da plataforma (prefixo fayz_) em ~/.fayz/credentials.json (modo 0600, só o dono lê). Sem --token, ele lê da env FAYZ_TOKEN ou pede interativamente (num shell não interativo sem token, falha rápido com instruções). --status mostra a credencial mascarada, sem rede. Não há validação de rede no login — o token é validado no primeiro deploy.
• fayz logout — apaga a credencial salva.
• fayz deploy [dir] [--dry-run | --yes] — coleta os arquivos de fonte do app, cria/vincula um projeto na plataforma e dispara o build server-side com host estático. O vínculo do projeto fica em <app>/.fayz/project.json (adicione .fayz/ ao seu .gitignore). O app publicado fica em https://<app>.live.fayz.ai. --dry-run não faz nenhuma chamada de rede; um deploy real pede confirmação a menos que --yes.

Resolução de token e URL: o token vem de FAYZ_TOKEN (env, prioridade) → ~/.fayz/credentials.json. A URL da API vem de FAYZ_API_URL (default https://beta.fayz.ai/api). O passo a passo com screenshots está em Deploy na Fayz.

Próximo: os campos que o doctor valida em Manifesto do plugin — referência.