Comandos

Visão geral

A CLI kubojs oferece vários comandos para gerenciar seus projetos TypeScript.

`create` (comando padrão)

Cria um novo projeto kubojs.

kubojs [project-directory] [options]

Parâmetros

project-directory (opcional): Nome ou caminho do diretório do projeto

Opções principais

--yes, -y: Usa a configuração padrão (pula prompts)
--dry-run: Valida a configuração e o diretório de destino sem gravar arquivos
--verbose: Mostra informações detalhadas do resultado em JSON
--yolo: Ignora validações e checagens de compatibilidade
--package-manager <pm>: npm, pnpm, bun
--install / --no-install: Instala dependências após a criação
--git / --no-git: Inicializa repositório Git
--frontend <types...>: Frameworks web e/ou native (veja Opções)
--backend <framework>: hono, express, fastify, elysia, convex, self, none
--runtime <runtime>: bun, node, workers (none apenas com --backend convex, --backend none ou --backend self)
--database <type>: none, sqlite, postgres, mysql, mongodb
--orm <type>: none, drizzle, prisma, mongoose
--api <type>: none, trpc, orpc
--auth <provider>: better-auth, clerk, none (veja Opções)
--payments <provider>: none
--db-setup <setup>: none, turso, d1, neon, supabase, prisma-postgres, planetscale, mongodb-atlas, docker
--examples <types...>: none, todo, ai
--web-deploy <setup>: none, cloudflare
--server-deploy <setup>: none, cloudflare
--template <type>: none, mern, pern, t3, uniwind
--directory-conflict <strategy>: merge, overwrite, increment, error
--render-title / --no-render-title: Mostra/oculta o título em ASCII art
--disable-analytics / --no-disable-analytics: Controla a coleta de analytics
--manual-db: Pula prompts de setup automático de banco de dados

Veja a referência completa em Opções.

Para automação JSON-first e uso por agentes, veja Fluxos de agente.

Exemplos

# Default setup with prompts
kubojs

# Quick setup with defaults
kubojs --yes

# Specific configuration
kubojs --database postgres --backend hono --frontend tanstack-router

# Validate without writing files
kubojs my-app --yes --dry-run

`add`

Adiciona addons a um projeto kubojs existente.

kubojs add [options]

Opções

--addons <types...>: Addons a adicionar (veja Addons)
--project-dir <path>: Diretório do projeto (padrão: diretório atual)
--install / --no-install: Instala dependências após adicionar
--package-manager <pm>: Gerenciador de pacotes a usar (npm, pnpm, bun)

Exemplos

# Add addons interactively
kubojs add

# Add specific addons
kubojs add --addons pwa tauri --install

# Add addons in a specific project directory
kubojs add --project-dir ./my-app --addons mcp skills

`create-json`

Cria um projeto a partir de um payload JSON bruto.

kubojs create-json --input '{"projectName":"my-app","yes":true,"dryRun":true}'

Use quando quiser um único objeto de entrada legível por máquina em vez de muitas flags.

`add-json`

Adiciona addons a partir de um payload JSON bruto.

kubojs add-json --input '{"projectDir":"./my-app","addons":["wxt"],"addonOptions":{"wxt":{"template":"react"}}}'

`schema`

Imprime schemas de runtime da CLI e de input como JSON.

kubojs schema --name all
kubojs schema --name createInput
kubojs schema --name addonOptions
kubojs schema --name dbSetupOptions

Esta é a melhor forma de scripts e agentes descobrirem o contrato de input atual em runtime.

`mcp`

Inicia o servidor MCP do kubojs via stdio. É lançado por um cliente MCP (Claude Code, Codex, Cursor, opencode e outros), não executado diretamente.

kubojs mcp

Expõe tools para planejar e criar projetos (bts_plan_project, bts_create_project) e gerenciar addons (bts_plan_addons, bts_add_addons), além de helpers de schema e orientação. Veja Fluxos de agente para setup e a lista completa de tools.

`sponsors`

Exibe os sponsors do kubojs.

kubojs sponsors

Mostra uma lista de sponsors e apoiadores do projeto.

`docs`

Abre a documentação do kubojs no navegador padrão.

kubojs docs

Abre https://kubojs.dev/docs no navegador.

`builder`

Abre o stack builder web no navegador padrão.

kubojs builder

Abre https://kubojs.dev/new, onde você configura a stack visualmente.

`history`

Mostra o histórico de criação de projetos armazenado localmente na máquina.

kubojs history [options]

Opções

--limit <number>: Número de entradas a mostrar (padrão: 10)
--json: Saída do histórico em JSON
--clear: Limpa todas as entradas do histórico

Exemplos

# Show latest entries
kubojs history

# Show 5 entries
kubojs history --limit 5

# JSON output
kubojs history --json

# Clear history
kubojs history --clear

Opções globais

Estas opções funcionam com qualquer comando:

--help, -h: Exibe informações de ajuda
--version, -V: Exibe a versão da CLI

Exemplos de comandos

Criar um app full-stack

kubojs \
  --database postgres \
  --orm drizzle \
  --backend hono \
  --frontend tanstack-router \
  --auth better-auth \
  --addons pwa biome

Criar um projeto só de backend

kubojs api-server \
  --frontend none \
  --backend hono \
  --database postgres \
  --orm drizzle \
  --api trpc

Adicionar recursos a um projeto existente

cd my-existing-project
kubojs add --addons tauri starlight --install

Mostrar histórico local

kubojs history --limit 20

Uso programático

Para casos avançados, automação ou integração com outras ferramentas, você pode usar a API programática para criar projetos a partir de código Node.js:

import { create } from "kubojs";

const result = await create("my-app", {
  frontend: ["tanstack-router"],
  backend: "hono",
  database: "sqlite",
  orm: "drizzle",
});

result.match({
  ok: (data) => console.log(`Project created at: ${data.projectDirectory}`),
  err: (error) => console.error(`Failed: ${error.message}`),
});

Isso é útil para:

Ferramentas de build e geradores — criar projetos a partir de templates
Pipelines de CI/CD — gerar projetos de teste automaticamente
Fluxos de desenvolvimento — criar em lote projetos relacionados
Tooling customizado — integrar com seu setup de desenvolvimento existente

Veja a documentação da API programática para exemplos completos e referência da API.

Comandos

Nesta página