CLI

Todos os comandos e flags do Blume explicados em um só lugar, junto com as opções que cada um aceita.

blume <command> [options]

Comandos

Flags comuns

• blume init — em um terminal, guia você por algumas perguntas (onde criar o projeto, nome do site, template, fontes de conteúdo); cada flag abaixo responde antecipadamente à sua pergunta.
• blume init --yes — pula as perguntas e cria a estrutura com os padrões (também é o comportamento em CI ou quando o stdin não é um terminal).
• blume init --content-dir <dir> — define a pasta de conteúdo (padrão docs).
• blume init --template docs|api|sdk|changelog — cria a estrutura a partir de um modelo inicial (referência de API, SDK ou changelog em vez da semente de documentação simples).
• blume init --package-manager npm|pnpm|yarn|bun — adapta os próximos passos exibidos ao seu gerenciador de pacotes.
• blume init --eject — cria a estrutura e depois faz eject para um projeto Astro independente (volta a guiar você por blume eject quando as dependências ainda não estão instaladas).
• blume dev --host --port <n> --open
• blume dev --content-dir <dir> — escaneia uma pasta de conteúdo diferente sem editar o blume.config.ts.
• blume dev --debug — log detalhado do Astro/Vite para resolução de problemas.
• blume dev --preview / blume build --preview — inclui rascunhos e conteúdo de CMS não publicado.
• blume build --no-strict — compila apesar de erros de diagnóstico. Por padrão, o blume build falha (código de saída 1) diante de qualquer diagnóstico de erro, porque as páginas que falham na validação do frontmatter são removidas do resultado; com --no-strict a compilação é bem-sucedida e informa quantas páginas estão faltando. O blume dev --strict faz o desenvolvimento adotar o mesmo comportamento de falha imediata.
• blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs — sobrescreve o resultado de deploy, o adaptador e o caminho base definidos no blume.config.ts.
• blume build --analyze — exibe os tamanhos dos bundles de JavaScript do cliente (do maior para o menor) após a compilação.
• blume build --budget-js <kb> --budget-css <kb> — faz a compilação falhar quando o total de JavaScript/CSS do cliente excede o orçamento, transformando uma meta de desempenho em uma barreira de CI.
• blume build --isolated — compila para um runtime descartável .blume-verify/ (e o seu próprio dist/) em vez de .blume/, para que um servidor blume dev em execução e o seu dist/ real fiquem intactos. Veja Verificar enquanto o servidor de desenvolvimento roda.
• blume preview --host --port <n> — vincula o servidor de pré-visualização.
• blume sync --force — busca novamente as fontes remotas, descartando primeiro o snapshot em cache.
• blume add <item> --force — sobrescreve os arquivos que já existem.
• blume check --preview — inclui rascunhos e conteúdo de CMS não publicado na verificação.
• blume check --strict — falha também diante de diagnósticos de conteúdo, além dos erros de tipos.
• blume check --isolated — verifica os tipos em um runtime descartável .blume-verify/ para que um servidor blume dev em execução fique intacto. Veja Verificar enquanto o servidor de desenvolvimento roda.
• blume eject --yes — pula o pedido de confirmação.
• blume validate --external — verifica também os links externos pela rede.
• blume validate --strict — sai com código diferente de zero também diante de avisos.
• blume validate --json / blume doctor --json — emite os diagnósticos em JSON no stdout (com code, severity, file, line/column e docsUrl) para integrações de CI e de editores.
• blume audit --fail-on error|warning|info — a barreira de CI; o padrão é error. --strict é um alias para --fail-on warning.
• blume audit --url <origin> — sonda também um deploy ativo em busca de códigos de status, cabeçalhos de resposta e cadeias de redirecionamento.
• blume audit --external — sonda os links de saída pela rede.
• blume audit --only <check|category> / --skip <check|category> — restringe o relatório enquanto você o resolve (separados por vírgulas).
• blume audit --list-checks — exibe todas as verificações que a auditoria pode reportar.
• blume audit --verbose — lista todas as páginas afetadas com o detalhe completo de cada constatação, como qual destino de link está quebrado.
• blume audit --json — emite o relatório em JSON no stdout.
• blume audit --claude / --codex — entrega as constatações ao Claude Code ou ao Codex para correção interativa.
• blume eval — executa as perguntas de evals.yaml através de um agente que lê apenas a sua documentação; veja Evals.
• blume eval init — faz o agente redigir um evals.yaml inicial a partir da sua documentação.
• blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose — veja Evals para cada flag.
• blume translate --claude / --codex — traduz páginas faltantes e desatualizadas para os idiomas configurados; veja Translate.
• blume translate --check — reporta o desvio de tradução e sai com código diferente de zero (a barreira de CI), sem executar um agente.
• blume translate --locale <codes> --concurrency <n> --force --timeout <seconds> --json — veja Translate para cada flag.

Verificar enquanto o servidor de desenvolvimento roda

O blume dev serve um servidor Astro ativo com raiz no runtime .blume/ gerado e o regenera a cada alteração. O blume build e o blume check regeneram o mesmo .blume/, então executar qualquer um deles com o servidor de desenvolvimento ativo iria corrompê-lo — ambos recusam com um erro e saem com código diferente de zero:

A `blume dev` server is running at http://localhost:3000; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.

A flag --isolated é a válvula de escape. Ela realoca todo o runtime gerado (e, no caso do build, o seu dist/ de saída) para um diretório irmão .blume-verify/, de modo que a verificação nunca escreva nada de que o servidor de desenvolvimento — ou o seu dist/ real — dependa:

# In a second terminal, while `blume dev` is running:
blume check --isolated   # fast: type-check the .astro/config changes
blume build --isolated   # thorough: full production render into .blume-verify/dist

O check --isolated é o caminho rápido (diagnósticos de tipos e de templates do Astro, sem dist/); o build --isolated é o mais pesado, que também detecta erros de renderização em tempo de execução. As compilações isoladas pulam os passos posteriores de deploy (índice de busca, sincronização com provedor hospedado, llms.txt, sitemap/robots, redirecionamentos) — uma verificação só precisa confirmar que o site compila e renderiza, não publicá-lo. O --analyze e as barreiras --budget-js/--budget-css continuam sendo executados, medidos em relação ao resultado isolado. O Blume adiciona automaticamente .blume-verify/ ao seu .gitignore.

Isso é especialmente útil quando um agente de programação precisa verificar alterações enquanto você mantém o servidor de desenvolvimento aberto. Para que o blume build/blume check simples isolem sem a flag — por exemplo, no shell de um agente — defina BLUME_RUNTIME_DIR com o diretório de runtime a usar:

export BLUME_RUNTIME_DIR=.blume-verify

Verificação de tipos

O blume check executa o astro check sobre o seu projeto. Ele regenera o runtime .blume, sincroniza os tipos de conteúdo do Astro e depois reporta quaisquer erros de TypeScript — no seu blume.config.ts, em páginas .astro personalizadas e nos componentes que elas importam. Ele sai com código diferente de zero quando existem erros, então funciona como um passo typecheck em CI:

{
  "scripts": {
    "typecheck": "blume check"
  }
}

Adicione à raiz do projeto um tsconfig.json que estenda a configuração do Astro, para que as páginas criadas resolvam as importações blume/* e módulos virtuais como blume:data:

{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
}

Sem um tsconfig.json no projeto, apenas o runtime gerado é verificado.

Validar links

O blume validate verifica todos os links descobertos no seu conteúdo:

• Links internos de páginas (/guides/intro, ./sibling) precisam resolver para uma página real — os que estiverem quebrados são reportados como erros.

• Links de âncora (#section, /guides/intro#setup) precisam corresponder a uma âncora na página de destino — o id de um cabeçalho (gerado ou fixado) ou o atributo id de um elemento HTML puro — e as falhas são reportadas como avisos. Ids dentro de blocos de código, código inline, comentários HTML e blocos <Prompt> não contam.

• Links de assets são verificados onde o arquivo fica: um caminho absoluto (/logo.png) em relação ao diretório public/, uma imagem incorporada com caminho relativo (![](./diagram.png)) em relação à pasta da própria página. Um link simples para um caminho relativo continua resolvendo como uma rota do site — apenas imagens incorporadas passam pelo pipeline de imagens.

• Links externos só são verificados com --external (desativado por padrão, já que requer rede); links mortos (404/410/inacessíveis) são erros, enquanto respostas com limite de taxa ou transitórias (403/429/5xx/timeout) são avisos.

Auditar o site compilado

O blume validate lê o seu conteúdo; o blume audit lê o site compilado. Ele rastreia o HTML em dist/ após uma compilação e reporta problemas de SEO e de saúde do site — títulos, meta descrições, canônicos, cards Open Graph e X, cabeçalhos, hreflang, imagens, o sitemap, o robots.txt e dados estruturados.

Como foi o Blume que compilou o site, cada constatação indica o arquivo de origem e a linha do front matter que a corrige, e não apenas a URL que um rastreador veria:

⚠ Meta description too long or too short   5 pages
    /docs/configuration/export    content/docs/configuration/export.mdx:3
    fix: Rewrite `description` in the frontmatter to fit the length range.

Execute-o após uma compilação:

blume build
blume audit

As constatações são agrupadas por verificação em vez de listadas por página, para que o relatório se leia como uma lista de tarefas. Use --verbose para expandir todas as páginas afetadas com o seu detalhe completo, e --only/--skip para tratar de uma categoria por vez. O blume audit --list-checks exibe o catálogo completo.

Fazer a CI falhar

O código de saída é o contrato. Por padrão, o blume audit só falha diante de erros — coisas que estão definitivamente quebradas, como um link para uma página que nunca foi compilada, um loop de redirecionamento ou um sitemap inválido. Constatações consultivas (uma descrição curta, um título duplicado) são avisos e não fazem a compilação falhar:

blume audit                      # fails on errors
blume audit --fail-on warning    # also fails on warnings

Verificar um deploy ativo

Há coisas que só o servidor real pode te dizer: se uma página que existe em dist/ realmente retorna 404 por trás de um rewrite incorreto, se as respostas estão comprimidas e se um cabeçalho X-Robots-Tag está discretamente desindexando uma página cujo HTML parece perfeitamente correto. Aponte a auditoria para um deploy para acrescentar essas verificações:

blume audit --url https://docs.example.com
blume audit --url https://docs.example.com --external   # also probe outbound links

Os links de saída são classificados em vez de simplesmente reprovados: um 404 é um link quebrado que você pode corrigir, enquanto um 403 ou 5xx normalmente é limitação de taxa ou uma indisponibilidade de terceiros e é reportado como aviso.

Corrigir as constatações com um agente

Se você usa o Claude Code ou o Codex, a auditoria pode entregar as suas constatações diretamente a ele:

blume audit --claude   # or --codex

Isso escreve o relatório JSON completo — todas as páginas afetadas, e não a prévia de três páginas do terminal — em um arquivo e abre o agente de forma interativa com um prompt que o orienta pelas constatações: editar o arquivo de origem que cada constatação indica, aplicar a correção sugerida e depois executar novamente blume build e blume audit até o relatório estar limpo. A sessão é interativa por design: você revisa as edições através do próprio fluxo de permissões do agente, e o agente é instruído a nunca corrigir uma constatação apagando conteúdo.

O --only e o --skip restringem a entrega da mesma forma que restringem o relatório, então você pode enviar uma categoria por vez.

O que ele verifica e o que não verifica

O conjunto de verificações é deliberadamente mais restrito do que o de um rastreador de SEO de uso geral. Muito do que esse rastreador reporta não pode acontecer a um site Blume — ele nunca emite rel=nofollow, e os bundles com hash de conteúdo do Vite nunca estão faltando nem redirecionando — e reportar isso como zeros permanentes só ensinaria você a ignorar o relatório.

Dois limites que vale a pena declarar com clareza:

• Dados estruturados são validados quanto à boa formação (JSON válido, um @context, um @type em cada nó). O Blume não valida em relação ao vocabulário completo do schema.org nem às regras de resultados enriquecidos do Google.
• Core Web Vitals não são verificados. Eles precisam de um navegador real, e uma flag que discretamente não medisse nada seria pior do que não tê-la — por isso o blume audit reporta as causas de deslocamento de layout que consegue ver offline (imagens sem width/height, assets superdimensionados) e deixa o resto de lado por enquanto.

Tudo o que a auditoria não executou é reportado como ignorado, em vez de passar silenciosamente:

⊘ network      skipped — pass --url <origin> (11 checks)
⊘ external     skipped — pass --external (2 checks)