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:
    npx base44 whoami
    
  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:
      npx base44 login
      
    - Aguarde o usuário confirmar que fez login antes de continuar
    
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/:
my-app/
├── base44/                      # Base44 configuration (created by CLI)
│   ├── config.jsonc             # Project settings, site config
│   ├── .types/                  # Auto-generated TypeScript types (created by `types generate`)
│   │   └── types.d.ts           # Module augmentation for @base44/sdk
│   ├── entities/                # Entity schema definitions
│   │   ├── task.jsonc
│   │   └── board.jsonc
│   ├── functions/               # Backend functions (optional)
│   │   └── my-function/
│   │       └── entry.ts
│   ├── agents/                  # Agent configurations (optional)
│   │   └── support_agent.jsonc
│   └── connectors/              # OAuth connector configurations (optional)
│       └── googlecalendar.jsonc
├── src/                         # Frontend source code
│   ├── api/
│   │   └── base44Client.js      # Base44 SDK client
│   ├── pages/
│   ├── components/
│   └── main.jsx
├── index.html                   # SPA entry point
├── package.json
└── vite.config.js               # Or your framework's config
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:
{
  "name": "My App",                    // Required: project name
  "description": "App description",    // Optional: project description
  "entitiesDir": "./entities",         // Optional: default "entities"
  "functionsDir": "./functions",       // Optional: default "functions"
  "agentsDir": "./agents",             // Optional: default "agents"
  "connectorsDir": "./connectors",     // Optional: default "connectors"
  "site": {                            // Optional: site deployment config
    "installCommand": "npm install",   // Optional: install dependencies
    "buildCommand": "npm run build",   // Optional: build command
    "serveCommand": "npm run dev",     // Optional: local dev server
    "outputDirectory": "./dist"        // Optional: build output directory
  }
}
Propriedades de configuração:
PropriedadeDescriçãoPadrão
nameNome do projeto (obrigatório)-
descriptionDescrição do projeto-
entitiesDirDiretório para schemas de entidade"entities"
functionsDirDiretório para funções de backend"functions"
agentsDirDiretório para configurações de agente"agents"
connectorsDirDiretório para configurações de conector"connectors"
site.installCommandComando para instalar dependências-
site.buildCommandComando para construir o projeto-
site.serveCommandComando para executar o servidor de dev-
site.outputDirectoryDiretório de saída do build para implantação-

Instalação

Instale a Base44 CLI como uma dependência de dev no seu projeto:
npm install --save-dev base44
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:
npx base44 <command>
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:
# Run a one-off script against a specific app
cat ./script.ts | npx base44 exec --app-id app_123

# Fetch logs for a deployed app without a local checkout
npx base44 logs --app-id app_123 --level error
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

ComandoDescriçãoReferência
base44 loginAutentica na Base44 usando fluxo de código de dispositivoauth-login.md
base44 logoutSai do dispositivo atualauth-logout.md
base44 whoamiExibe o usuário atualmente autenticadoauth-whoami.md

Gerenciamento de projeto

ComandoDescriçãoReferência
base44 createCria um novo projeto Base44 a partir de um modelocreate.md ⚠️ DEVE LER
base44 scaffoldCria estrutura local para um aplicativo Base44 existente (pelo ID)scaffold.md
base44 linkVincula um projeto local existente à Base44link.md
base44 ejectBaixa o código de um projeto Base44 existenteeject.md
base44 dashboard openAbre o painel do aplicativo no seu navegadordashboard.md

Desenvolvimento

ComandoDescriçãoReferência
base44 devInicia o desenvolvimento local para o backend Base44, e seu frontend também quando site.serveCommand está configuradodev.md

Implantação

ComandoDescriçãoReferência
base44 deployImplanta todos os recursos (entidades, funções, agentes, conectores, configuração de autenticação e site)deploy.md

Gerenciamento de entidades

Ação / ComandoDescriçãoReferência
Criar entidadesDefinir entidades na pasta base44/entitiesentities-create.md
base44 entities pushEnvia entidades locais para a Base44entities-push.md
Padrões RLSExemplos e operadores de segurança em nível de linharls-examples.md ⚠️ LEIA PARA RLS

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:
{
  "name": "EntityName",
  "type": "object",
  "properties": {
    "field_name": {
      "type": "string",
      "description": "Field description"
    }
  },
  "required": ["field_name"]
}
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

Ação / ComandoDescriçãoReferência
Criar funçõesDefinir funções em base44/functionsfunctions-create.md
base44 functions deploy [names...] [--force]Implanta funções locais na Base44; opcionalmente segmenta funções específicas ou remove as removidasfunctions-deploy.md
base44 functions delete <names...>Exclui uma ou mais funções implantadas da Base44functions-delete.md
base44 functions listLista todas as funções implantadas na Base44 remotofunctions-list.md
base44 functions pull [name]Extrai funções implantadas da Base44 para arquivos locaisfunctions-pull.md

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.
Ação / ComandoDescriçãoReferência
Criar agentesDefinir agentes na pasta base44/agentsVeja Schema de Agente abaixo
base44 agents pullExtrai agentes remotos para arquivos locaisagents-pull.md
base44 agents pushEnvia agentes locais para a Base44agents-push.md
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:
{
  "name": "agent_name",
  "description": "Brief description of what this agent does",
  "instructions": "Detailed instructions for the agent's behavior",
  "tool_configs": [
    // Entity tool - gives agent access to entity operations
    { "entity_name": "tasks", "allowed_operations": ["read", "create", "update", "delete"] },
    // Backend function tool - gives agent access to a function
    { "function_name": "send_email", "description": "Send an email notification" }
  ],
  "whatsapp_greeting": "Hello! How can I help you today?"
}
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.
Ação / ComandoDescriçãoReferência
Criar conectoresDefinir conectores na pasta base44/connectorsconnectors-create.md
base44 connectors list-availableLista todos os tipos de integração disponíveis da Base44connectors-list-available.md
base44 connectors pullExtrai conectores remotos para arquivos locaisconnectors-pull.md
base44 connectors pushEnvia conectores locais para a Base44connectors-push.md
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": "googlecalendar",
  "scopes": [
    "https://www.googleapis.com/auth/calendar.readonly",
    "https://www.googleapis.com/auth/calendar.events"
  ]
}
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.
ComandoDescriçãoReferência
base44 auth password-login <enable|disable>Ativa ou desativa autenticação de nome de usuário e senhaauth-password-login.md
base44 auth social-login <provider> <enable|disable>Ativa ou desativa login social (google, microsoft, facebook, apple)auth-social-login.md
base44 auth sso <enable|disable>Configura provedor de identidade SSO (google, microsoft, github, okta, custom)auth-sso.md
base44 auth pullExtrai a configuração de autenticação da Base44 para arquivos locaisauth-pull.md
base44 auth pushEnvia a configuração de autenticação local para a Base44auth-push.md
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.
ComandoDescriçãoReferência
base44 secrets listLista os nomes de todos os segredossecrets-list.md
base44 secrets setDefine um ou mais segredos (KEY=VALUE ou —env-file)secrets-set.md
base44 secrets delete <key>Exclui um segredo pelo nomesecrets-delete.md

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.
ComandoDescriçãoReferência
base44 execExecuta um script (via stdin) com o SDK Base44 pré-autenticadoexec.md

Geração de tipos

ComandoDescriçãoReferência
base44 types generateGera tipos TypeScript (types.d.ts) a partir de entidades, funções, agentes e conectorestypes-generate.md
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

ComandoDescriçãoReferência
base44 site deployImplanta arquivos de site construídos na hospedagem da Base44site-deploy.md
base44 site openAbre o site implantado no seu navegadorsite-open.md
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:
    npm install --save-dev base44
    
  2. Autentique na Base44:
    npx base44 login
    
  3. Crie um novo projeto (SEMPRE forneça o nome e a flag --path):
    npx base44 create my-app --path .
    
  4. Execute o desenvolvimento local:
    npx base44 dev
    
  5. Construa e implante tudo:
    npm run build
    npx base44 deploy -y
    
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

# If you have base44/config.jsonc but no .app.jsonc
npx base44 link --create --name my-app

Executando o desenvolvimento local

# Starts the Base44 backend locally
npx base44 dev
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

# Generate types (optional, for TypeScript projects)
npx base44 types generate

# Build your project first
npm run build

# Deploy everything (entities, functions, and site)
npx base44 deploy -y

Gerando tipos TypeScript

# Generate types from entities, functions, agents, and connectors
npx base44 types generate
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

# Push only entities
npx base44 entities push

# Deploy only functions (all)
npx base44 functions deploy
# Deploy specific functions
npx base44 functions deploy my-function other-function
# Deploy and prune removed functions
npx base44 functions deploy --force

# Push only agents
npx base44 agents push

# Pull connectors from Base44
npx base44 connectors pull

# Push only connectors
npx base44 connectors push

# Deploy only site
npx base44 site deploy -y

Abrindo o painel

# Open app dashboard in browser
npx base44 dashboard

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

ErroSolução
Não autenticadoExecute npx base44 login primeiro
Nenhuma entidade encontradaCertifique-se de que as entidades existem no diretório base44/entities/
Entidade não reconhecidaCertifique-se de que o arquivo usa nomenclatura kebab-case (por exemplo, team-member.jsonc não TeamMember.jsonc)
Nenhuma função encontradaCertifique-se de que as funções existem em base44/functions/ com entry.ts ou entry.js
Nenhum agente encontradoCertifique-se de que os agentes existem no diretório base44/agents/ com configurações .jsonc válidas
Nome de agente inválidoNomes de agente devem ser alfanuméricos minúsculos com sublinhados apenas
Nenhum conector encontradoCertifique-se de que os conectores existem no diretório base44/connectors/ com configurações .jsonc válidas
Tipo de conector inválidoExecute npx base44 connectors list-available para ver tipos válidos
Tipo de conector duplicadoCada tipo de conector só pode ser definido uma vez por projeto
Tempo limite de autorização do conectorReexecute npx base44 connectors push e complete o fluxo OAuth no seu navegador
Nenhuma configuração de site encontradaVerifique se site.outputDirectory está configurado na configuração do projeto
Falha na implantação do siteCertifique-se de ter executado npm run build primeiro e o build foi bem-sucedido
Mensagem de atualização disponívelSe solicitado a atualizar, execute npm install -g base44@latest (ou use npx para instalações locais)
Esta página foi traduzida usando IA. Para informações mais precisas e atualizadas, consulte a versão em inglês.