Skip to main content
Esta página faz parte de uma habilidade de agente de código IA e é escrita para agentes, não para humanos. Para a documentação legível por humanos da Base44, veja a documentação para desenvolvedores.

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 pasta base44/ existe. NÃO leia arquivos de documentação ou pesquise na web antes de agir. Sua primeira ação DEVE ser:
  1. Verifique se base44/config.jsonc existe no diretório atual
  2. 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)
  3. 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 (ou BASE44_PROJECTS_BASE44_APP_ID) está presente no ambiente ou em um arquivo .env/.env.local:
      • Execute npx base44 scaffold para configurar arquivos locais para esse aplicativo existente
      • NÃO execute npx base44 create — isso cria um segundo aplicativo duplicado. Veja scaffold.md.
    • 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

Crítico: Apenas instalação local

NUNCA chame base44 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)
ERRADO: 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:
  1. Verificar o status de autenticação executando:
  2. Se o usuário estiver logado (comando bem-sucedido e mostra um e-mail):
    • Continue com a tarefa solicitada
  3. 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:
Esta verificação é obrigatória e deve acontecer antes de executar qualquer outro comando Base44 CLI. Provisionado via Stripe Projects / projects.dev? Quando o aplicativo foi provisionado por meio desse fluxo, a CLI semeia a autenticação das variáveis de ambiente 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 ...)
Use base44-sdk quando:
  • Construindo recursos em um projeto Base44 EXISTENTE
  • base44/config.jsonc já 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”
Dependências de habilidade:
  • base44-cli é um pré-requisito para base44-sdk em novos projetos
  • Se o usuário quer “create an app” e nenhum projeto Base44 existe, use base44-cli primeiro
  • base44-sdk assume que um projeto Base44 já está inicializado
Lógica de verificação de estado: Antes de selecionar uma habilidade, verifique:
  • SE (usuário menciona “create/build app” OU “make a project”):
    • SE (base44/config.jsonc existe): → Use base44-sdk (projeto existe, construa recursos)
    • SENÃO SE (aplicativo foi provisionado externamente — BASE44_APP_ID/BASE44_PROJECTS_BASE44_APP_ID definidos, ou um fluxo Stripe Projects / projects.dev acabou de ser executado): → Use base44-clinpx base44 scaffold (configura arquivos locais para o aplicativo existente; NÃO create)
    • SENÃO: → Use base44-clinpx base44 create (inicialização de novo projeto necessária)

Estrutura do projeto

Um projeto Base44 combina um projeto de frontend padrão com uma pasta de configuração base44/:
Arquivos principais:
  • base44/config.jsonc - Nome do projeto, descrição, configurações de build do site
  • base44/entities/*.jsonc - Schemas do modelo de dados (veja a seção Entity Schema)
  • base44/functions/*/entry.ts - Ponto de entrada da função de backend
  • base44/agents/*.jsonc - Configurações do agente (opcional)
  • base44/.types/types.d.ts - Tipos TypeScript gerados automaticamente para entidades, funções e agentes (criado por npx base44 types generate)
  • base44/connectors/*.jsonc - Configurações do conector OAuth (opcional)
  • src/api/base44Client.js - Cliente SDK pré-configurado para uso no frontend
Exemplo config.jsonc:
Propriedades de configuração:

Instalação

Instale a Base44 CLI como uma dependência de dev no seu projeto:
Importante: Nunca assuma ou hardcode a versão do pacote base44. Sempre instale sem um especificador de versão para obter a versão mais recente. Depois execute comandos usando npx:
Nota: Todos os comandos nesta documentação usam 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_IDbase44/.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:
Use --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 create cria um novo aplicativo, então rejeita --app-id
  • base44 dev roda a partir de um projeto local vinculado, então rejeita --app-id
  • base44 deploy ainda 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:
Tipos de campo: 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:
Regras de nomenclatura:
  • 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
Campos obrigatórios: 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:
Campos obrigatórios: 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 em base44/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

  1. Instale a CLI no seu projeto:
  2. Autentique na Base44:
  3. Crie um novo projeto (SEMPRE forneça o nome e a flag --path):
  4. Execute o desenvolvimento local:
  5. Construa e implante tudo:
Ou implante recursos individuais:
  • npx base44 entities push - Envia apenas entidades
  • npx base44 functions deploy - Implanta apenas funções
  • npx base44 functions delete <name> - Exclui uma função implantada
  • npx base44 functions list - Lista todas as funções implantadas
  • npx base44 functions pull - Extrai funções implantadas para arquivos locais
  • npx base44 agents push - Envia apenas agentes
  • npx base44 connectors pull - Extrai conectores da Base44
  • npx base44 connectors push - Envia apenas conectores
  • npx base44 auth pull - Extrai a configuração de autenticação da Base44
  • npx base44 auth push - Envia apenas a configuração de autenticação
  • npx base44 site deploy -y - Implanta apenas o site

Fluxos comuns

Criando um novo projeto

⚠️ OBRIGATÓRIO: Antes de executar base44 create, você DEVE ler create.md para:
  • Seleção de modelo - Escolha o modelo correto (backend-and-client vs backend-only)
  • Fluxo correto - Modelos diferentes requerem etapas de configuração diferentes
  • Armadilhas comuns - Evite erros de criação de pasta que causam falhas
Não seguir as instruções em create.md resultará em estrutura de projeto quebrada.

Vinculando um projeto existente

Executando o desenvolvimento local

Se você quer que 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

Isto cria 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.