Base44 CLI
Crie e gerencie aplicativos Base44 (projetos) usando a ferramenta Base44 CLI.⚡ AÇÃO IMEDIATA NECESSÁRIA - Leia isto primeiro
Esta habilidade é ativada em QUALQUER menção a “base44” ou quando uma pastabase44/ existe. NÃO leia arquivos de documentação ou pesquise na web antes de agir.
Sua primeira ação DEVE ser:
- Verifique se
base44/config.jsoncexiste no diretório atual - Se SIM (cenário de projeto existente):
- Transfira para a habilidade base44-sdk para implementação
- Esta habilidade lida apenas com comandos CLI (login, deploy, entities push)
- Se NÃO, decida entre dois caminhos de inicialização:
- Aplicativo provisionado — o aplicativo Base44 já existe porque foi provisionado por um fluxo Stripe Projects / projects.dev, OU
BASE44_APP_ID(ouBASE44_PROJECTS_BASE44_APP_ID) está presente no ambiente ou em um arquivo.env/.env.local:- Execute
npx base44 scaffoldpara configurar arquivos locais para esse aplicativo existente - NÃO execute
npx base44 create— isso cria um segundo aplicativo duplicado. Veja scaffold.md.
- Execute
- Novo projeto — nenhum aplicativo existe ainda e nenhum foi provisionado:
- Esta habilidade (base44-cli) lida com a solicitação; guie o usuário através de
npx base44 create - NÃO ative base44-sdk ainda
- Esta habilidade (base44-cli) lida com a solicitação; guie o usuário através de
- Aplicativo provisionado — o aplicativo Base44 já existe porque foi provisionado por um fluxo Stripe Projects / projects.dev, OU
Crítico: Apenas instalação local
NUNCA chamebase44 diretamente. A CLI é instalada localmente como uma dependência de desenvolvimento e deve ser acessada via um gerenciador de pacotes:
npx base44 <command>(npm - recomendado)yarn base44 <command>(yarn)pnpm base44 <command>(pnpm)
base44 login
CERTO: npx base44 login
OBRIGATÓRIO: Verificação de autenticação no início da sessão
CRÍTICO: No início de cada sessão de IA quando esta habilidade é ativada, você DEVE:-
Verificar o status de autenticação executando:
-
Se o usuário estiver logado (comando bem-sucedido e mostra um e-mail):
- Continue com a tarefa solicitada
-
Se o usuário NÃO estiver logado (comando falha ou mostra um erro):
- PARE imediatamente
- NÃO prossiga com quaisquer operações CLI
- Peça ao usuário para fazer login manualmente executando:
BASE44_ACCESS_TOKEN / BASE44_REFRESH_TOKEN que ela injeta (os nomes com prefixo BASE44_PROJECTS_* são normalizados automaticamente). Nesse caso, npx base44 whoami já é bem-sucedido e você não precisa de um npx base44 login interativo.
Visão geral
A CLI Base44 fornece ferramentas de linha de comando para autenticação, criação de projetos, gerenciamento de entidades e implantação de aplicativos Base44. É agnóstica a frameworks e funciona com frameworks de frontend populares como Vite, Next.js, Create React App, Svelte, Vue e mais.Quando usar esta habilidade vs base44-sdk
Use base44-cli quando:- Criando um NOVO projeto Base44 do zero
- Inicializando um projeto em um diretório vazio
- Configurando arquivos locais para um aplicativo existente provisionado externamente (por exemplo, por um fluxo Stripe Projects / projects.dev) → use
scaffold - O diretório está faltando
base44/config.jsonc - O usuário menciona: “create a new project”, “initialize project”, “setup a project”, “start a new Base44 app”
- Implantando, enviando entidades ou autenticando via CLI
- Trabalhando com comandos CLI (
npx base44 ...)
- Construindo recursos em um projeto Base44 EXISTENTE
base44/config.jsoncjá existe- Escrevendo código JavaScript/TypeScript usando o SDK Base44
- Implementando funcionalidade, componentes ou recursos
- O usuário menciona: “implement”, “build a feature”, “add functionality”, “write code”
base44-clié um pré-requisito parabase44-sdkem novos projetos- Se o usuário quer “create an app” e nenhum projeto Base44 existe, use
base44-cliprimeiro base44-sdkassume que um projeto Base44 já está inicializado
- SE (usuário menciona “create/build app” OU “make a project”):
- SE (
base44/config.jsoncexiste): → Use base44-sdk (projeto existe, construa recursos) - SENÃO SE (aplicativo foi provisionado externamente —
BASE44_APP_ID/BASE44_PROJECTS_BASE44_APP_IDdefinidos, ou um fluxo Stripe Projects / projects.dev acabou de ser executado): → Use base44-cli →npx base44 scaffold(configura arquivos locais para o aplicativo existente; NÃOcreate) - SENÃO:
→ Use base44-cli →
npx base44 create(inicialização de novo projeto necessária)
- SE (
Estrutura do projeto
Um projeto Base44 combina um projeto de frontend padrão com uma pasta de configuraçãobase44/:
base44/config.jsonc- Nome do projeto, descrição, configurações de build do sitebase44/entities/*.jsonc- Schemas do modelo de dados (veja a seção Entity Schema)base44/functions/*/entry.ts- Ponto de entrada da função de backendbase44/agents/*.jsonc- Configurações do agente (opcional)base44/.types/types.d.ts- Tipos TypeScript gerados automaticamente para entidades, funções e agentes (criado pornpx base44 types generate)base44/connectors/*.jsonc- Configurações do conector OAuth (opcional)src/api/base44Client.js- Cliente SDK pré-configurado para uso no frontend
Instalação
Instale a Base44 CLI como uma dependência de dev no seu projeto:base44. Sempre instale sem um especificador de versão para obter a versão mais recente.
Depois execute comandos usando npx:
npx base44. Você também pode usar yarn base44 ou pnpm base44 se preferir.
Opção global --app-id
A CLI tem uma opção global --app-id <id> para comandos que precisam apenas de um contexto de aplicativo, não de arquivos locais do projeto.
Ordem de resolução: flag --app-id → variável de ambiente BASE44_APP_ID → base44/.app.jsonc local
Isto é útil quando você quer inspecionar ou operar em um aplicativo sem mudar para um diretório de projeto vinculado. Exemplos comuns:
--app-id para comandos com escopo de aplicativo como exec e logs.
Não use --app-id para comandos que precisam de arquivos locais do projeto:
base44 createcria um novo aplicativo, então rejeita--app-idbase44 devroda a partir de um projeto local vinculado, então rejeita--app-idbase44 deployainda requer um diretório de projeto local porque lê recursos locais
Comandos disponíveis
Autenticação
Gerenciamento de projeto
Desenvolvimento
Implantação
Gerenciamento de entidades
Schema de entidade (Referência rápida)
SEMPRE siga esta estrutura exata ao criar arquivos de entidade: Nomenclatura de arquivo:base44/entities/{kebab-case-name}.jsonc (por exemplo, team-member.jsonc para TeamMember)
Modelo de schema:
string, number, integer, boolean, array, object, binary
Formatos de string: date, date-time, time, email, uri, hostname, ipv4, ipv6, uuid, file, regex, richtext
Para enums: Adicione "enum": ["value1", "value2"] e opcionalmente "default": "value1"
Nomes de entidade: Deve ser apenas alfanumérico (padrão: /^[a-zA-Z0-9]+$/)
Para documentação completa, veja entities-create.md.
Gerenciamento de funções
Gerenciamento de agentes
Agentes são assistentes de IA conversacionais que podem interagir com usuários, acessar as entidades do seu aplicativo e chamar funções de backend. Use esses comandos para gerenciar configurações de agente.
Nota: Comandos de agente realizam sincronização completa - o push substitui todos os agentes remotos pelos locais, e o pull substitui todos os agentes locais pelos remotos.
Schema de agente (Referência rápida)
Nomenclatura de arquivo:base44/agents/{agent_name}.jsonc (por exemplo, support_agent.jsonc)
Modelo de schema:
- Nomes de agente devem corresponder ao padrão:
/^[a-z0-9_]+$/(alfanumérico minúsculo com sublinhados, 1-100 caracteres) - Válido:
support_agent,order_bot - Inválido:
Support-Agent,OrderBot
name, description, instructions
Campos opcionais: tool_configs (padrão para []), whatsapp_greeting
Tipos de tool config:
- Ferramentas de entidade:
entity_name+allowed_operations(array de:read,create,update,delete) - Ferramentas de função de backend:
function_name+description
Gerenciamento de conectores
Conectores permitem que seu aplicativo se conecte a serviços externos (Google Calendar, Slack, Stripe, etc.). A maioria dos conectores usa OAuth para fornecer tokens de acesso para funções de backend chamarem APIs externas. Stripe é a exceção — é provisionado automaticamente no lado do servidor sem fluxo de navegador OAuth.
Nota: Comandos de conector realizam sincronização completa - o push substitui todos os conectores remotos pelos locais (e dispara OAuth para novos conectores OAuth), e o pull substitui todos os conectores locais pelos remotos.
Schema de conector (Referência rápida)
Nomenclatura de arquivo:base44/connectors/{type}.jsonc (por exemplo, googlecalendar.jsonc, slack.jsonc)
Modelo de schema:
type
Campos opcionais: scopes (padrão para [])
Tipos de conector disponíveis: Execute npx base44 connectors list-available para ver todos os tipos de integração suportados.
Nota: stripe também é um tipo de conector válido, mas não é retornado por list-available. Trate-o como um tipo suportado — é provisionado automaticamente pela Base44 sem fluxo de navegador OAuth. Veja connectors-create.md para detalhes.
Para documentação completa, veja connectors-create.md.
Configuração de autenticação
Gerencie as configurações de autenticação do seu aplicativo (por exemplo, login por nome de usuário e senha). A configuração de autenticação é armazenada embase44/auth/ e sincronizada com a Base44 via auth push/auth pull.
Nota: A configuração de autenticação também é implantada como parte de
base44 deploy.
Gerenciamento de segredos
Gerencie segredos do projeto (variáveis de ambiente armazenadas com segurança na Base44). Esses comandos estão ocultos da saída--help mas são totalmente funcionais.
Execução de script
Execute scripts únicos contra seu aplicativo com o SDK Base44 pré-autenticado. Use-o para realizar operações CRUD em entidades (base44.entities.MyEntity.list/create/update/delete), chamar funções de backend (base44.functions.invoke("myFunction", args)), invocar agentes ou acessar qualquer outro recurso exposto pelo SDK — sem implantar uma função completa. Útil para migrações de dados, operações em massa, depuração e fluxos de trabalho de script.
Geração de tipos
Saída:
base44/.types/types.d.ts — aumenta o módulo @base44/sdk com registros tipados (EntityTypeRegistry, FunctionNameRegistry, AgentNameRegistry, ConnectorTypeRegistry).
Nenhuma autenticação necessária. Roda inteiramente localmente. Atualiza automaticamente tsconfig.json para incluir os tipos gerados.
Gerenciamento de site
Apenas SPA: A hospedagem da Base44 suporta aplicativos de página única com um único ponto de entrada
index.html. Todas as rotas são servidas de index.html (roteamento no lado do cliente).
Início rápido
-
Instale a CLI no seu projeto:
-
Autentique na Base44:
-
Crie um novo projeto (SEMPRE forneça o nome e a flag
--path): -
Execute o desenvolvimento local:
-
Construa e implante tudo:
npx base44 entities push- Envia apenas entidadesnpx base44 functions deploy- Implanta apenas funçõesnpx base44 functions delete <name>- Exclui uma função implantadanpx base44 functions list- Lista todas as funções implantadasnpx base44 functions pull- Extrai funções implantadas para arquivos locaisnpx base44 agents push- Envia apenas agentesnpx base44 connectors pull- Extrai conectores da Base44npx base44 connectors push- Envia apenas conectoresnpx base44 auth pull- Extrai a configuração de autenticação da Base44npx base44 auth push- Envia apenas a configuração de autenticaçãonpx base44 site deploy -y- Implanta apenas o site
Fluxos comuns
Criando um novo projeto
⚠️ OBRIGATÓRIO: Antes de executarbase44 create, você DEVE ler create.md para:
- Seleção de modelo - Escolha o modelo correto (
backend-and-clientvsbackend-only) - Fluxo correto - Modelos diferentes requerem etapas de configuração diferentes
- Armadilhas comuns - Evite erros de criação de pasta que causam falhas
Vinculando um projeto existente
Executando o desenvolvimento local
base44 dev execute seu frontend também, verifique se base44/config.jsonc tem site.serveCommand definido corretamente (por exemplo, "serveCommand": "npm run dev"). Quando esse campo está presente, base44 dev executa tanto o backend quanto o frontend juntos.
Implantando todas as alterações
Gerando tipos TypeScript
base44/.types/types.d.ts com registros tipados para o módulo @base44/sdk. Execute isto após alterar entidades, funções, agentes ou conectores para manter seus tipos sincronizados. Nenhuma autenticação necessária.
Implantando recursos individuais
Abrindo o painel
Autenticação
A maioria dos comandos requer autenticação. Se você não está logado, a CLI solicitará automaticamente que você faça login. Sua sessão é armazenada localmente e persiste em várias sessões da CLI.Solução de problemas
Esta página foi traduzida usando IA. Para informações mais precisas e atualizadas, consulte a versão em inglês.