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
| Propriedade | Descrição | Padrão |
|---|---|---|
name | Nome do projeto (obrigatório) | - |
description | Descrição do projeto | - |
entitiesDir | Diretório para schemas de entidade | "entities" |
functionsDir | Diretório para funções de backend | "functions" |
agentsDir | Diretório para configurações de agente | "agents" |
connectorsDir | Diretório para configurações de conector | "connectors" |
site.installCommand | Comando para instalar dependências | - |
site.buildCommand | Comando para construir o projeto | - |
site.serveCommand | Comando para executar o servidor de dev | - |
site.outputDirectory | Diretório de saída do build para implantação | - |
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
| Comando | Descrição | Referência |
|---|---|---|
base44 login | Autentica na Base44 usando fluxo de código de dispositivo | auth-login.md |
base44 logout | Sai do dispositivo atual | auth-logout.md |
base44 whoami | Exibe o usuário atualmente autenticado | auth-whoami.md |
Gerenciamento de projeto
| Comando | Descrição | Referência |
|---|---|---|
base44 create | Cria um novo projeto Base44 a partir de um modelo | create.md ⚠️ DEVE LER |
base44 scaffold | Cria estrutura local para um aplicativo Base44 existente (pelo ID) | scaffold.md |
base44 link | Vincula um projeto local existente à Base44 | link.md |
base44 eject | Baixa o código de um projeto Base44 existente | eject.md |
base44 dashboard open | Abre o painel do aplicativo no seu navegador | dashboard.md |
Desenvolvimento
| Comando | Descrição | Referência |
|---|---|---|
base44 dev | Inicia o desenvolvimento local para o backend Base44, e seu frontend também quando site.serveCommand está configurado | dev.md |
Implantação
| Comando | Descrição | Referência |
|---|---|---|
base44 deploy | Implanta todos os recursos (entidades, funções, agentes, conectores, configuração de autenticação e site) | deploy.md |
Gerenciamento de entidades
| Ação / Comando | Descrição | Referência |
|---|---|---|
| Criar entidades | Definir entidades na pasta base44/entities | entities-create.md |
base44 entities push | Envia entidades locais para a Base44 | entities-push.md |
| Padrões RLS | Exemplos e operadores de segurança em nível de linha | rls-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:
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 / Comando | Descrição | Referência |
|---|---|---|
| Criar funções | Definir funções em base44/functions | functions-create.md |
base44 functions deploy [names...] [--force] | Implanta funções locais na Base44; opcionalmente segmenta funções específicas ou remove as removidas | functions-deploy.md |
base44 functions delete <names...> | Exclui uma ou mais funções implantadas da Base44 | functions-delete.md |
base44 functions list | Lista todas as funções implantadas na Base44 remoto | functions-list.md |
base44 functions pull [name] | Extrai funções implantadas da Base44 para arquivos locais | functions-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 / Comando | Descrição | Referência |
|---|---|---|
| Criar agentes | Definir agentes na pasta base44/agents | Veja Schema de Agente abaixo |
base44 agents pull | Extrai agentes remotos para arquivos locais | agents-pull.md |
base44 agents push | Envia agentes locais para a Base44 | agents-push.md |
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.| Ação / Comando | Descrição | Referência |
|---|---|---|
| Criar conectores | Definir conectores na pasta base44/connectors | connectors-create.md |
base44 connectors list-available | Lista todos os tipos de integração disponíveis da Base44 | connectors-list-available.md |
base44 connectors pull | Extrai conectores remotos para arquivos locais | connectors-pull.md |
base44 connectors push | Envia conectores locais para a Base44 | connectors-push.md |
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.
| Comando | Descrição | Referência |
|---|---|---|
base44 auth password-login <enable|disable> | Ativa ou desativa autenticação de nome de usuário e senha | auth-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 pull | Extrai a configuração de autenticação da Base44 para arquivos locais | auth-pull.md |
base44 auth push | Envia a configuração de autenticação local para a Base44 | auth-push.md |
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.
| Comando | Descrição | Referência |
|---|---|---|
base44 secrets list | Lista os nomes de todos os segredos | secrets-list.md |
base44 secrets set | Define um ou mais segredos (KEY=VALUE ou —env-file) | secrets-set.md |
base44 secrets delete <key> | Exclui um segredo pelo nome | secrets-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.
| Comando | Descrição | Referência |
|---|---|---|
base44 exec | Executa um script (via stdin) com o SDK Base44 pré-autenticado | exec.md |
Geração de tipos
| Comando | Descrição | Referência |
|---|---|---|
base44 types generate | Gera tipos TypeScript (types.d.ts) a partir de entidades, funções, agentes e conectores | types-generate.md |
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
| Comando | Descrição | Referência |
|---|---|---|
base44 site deploy | Implanta arquivos de site construídos na hospedagem da Base44 | site-deploy.md |
base44 site open | Abre o site implantado no seu navegador | site-open.md |
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
| Erro | Solução |
|---|---|
| Não autenticado | Execute npx base44 login primeiro |
| Nenhuma entidade encontrada | Certifique-se de que as entidades existem no diretório base44/entities/ |
| Entidade não reconhecida | Certifique-se de que o arquivo usa nomenclatura kebab-case (por exemplo, team-member.jsonc não TeamMember.jsonc) |
| Nenhuma função encontrada | Certifique-se de que as funções existem em base44/functions/ com entry.ts ou entry.js |
| Nenhum agente encontrado | Certifique-se de que os agentes existem no diretório base44/agents/ com configurações .jsonc válidas |
| Nome de agente inválido | Nomes de agente devem ser alfanuméricos minúsculos com sublinhados apenas |
| Nenhum conector encontrado | Certifique-se de que os conectores existem no diretório base44/connectors/ com configurações .jsonc válidas |
| Tipo de conector inválido | Execute npx base44 connectors list-available para ver tipos válidos |
| Tipo de conector duplicado | Cada tipo de conector só pode ser definido uma vez por projeto |
| Tempo limite de autorização do conector | Reexecute npx base44 connectors push e complete o fluxo OAuth no seu navegador |
| Nenhuma configuração de site encontrada | Verifique se site.outputDirectory está configurado na configuração do projeto |
| Falha na implantação do site | Certifique-se de ter executado npm run build primeiro e o build foi bem-sucedido |
| Mensagem de atualização disponível | Se 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.

