Espobase CLI
Trabalhe com seus projetos pelo terminal: vincule uma pasta a um projeto, gere tipos TypeScript, execute consultas somente leitura e confira logs e uso. Requer Node.js 20 ou mais recente.
Primeiros passos
npx espobase login # opens your browser: sign in and click Allow npx espobase init # link this folder, write espobase.types.ts, show your app's settings
Ou instale uma vez com npm install -g espobase e execute espobase ….
Comandos
| espobase login | Abre seu navegador: entre no Espobase e clique em Permitir. Em servidores, use --token espo_pat_…. |
| espobase init [<ref>] | Vincula esta pasta a um projeto, escreve espobase.types.ts e mostra o ESPOBASE_URL do seu app. |
| espobase projects list | Seus projetos, por organização. |
| espobase projects create <name> --org <slug> | Um novo projeto (o banco de dados dele fica pronto em instantes). |
| espobase link <ref> / unlink | Vincula esta pasta a um projeto (.espobase/project.json, pode ser incluído no commit). |
| espobase gen types [--out <file>] | Tipos TypeScript para createClient<Database>() no @espobase/client. |
| espobase db query "<sql>" | SQL somente leitura: SELECT, EXPLAIN, SHOW… |
| espobase migration new <name> | Um novo arquivo SQL em espobase/migrations, com a hora UTC atual no nome. |
| espobase migration list | Quais arquivos de migração estão aplicados, pendentes ou alterados. |
| espobase db push [--dry-run] | Aplica em ordem os arquivos de migração pendentes, cada um em uma transação. --dry-run os verifica e desfaz tudo. |
| espobase logs [--errors] | Requisições recentes à API: caminho, status, tempo (nunca corpos nem segredos). |
| espobase usage [--range 7d] | Requisições, largura de banda, armazenamento de banco de dados e de arquivos, uso de IA. |
| espobase storage ls [<bucket>] | Seus buckets, ou os arquivos de um deles. |
| espobase deploy <pasta> --site <endereço> | Publica uma pasta de build em um site hospedado e o coloca no ar (exige a permissão Fazer deploy de sites). `--message`, `--no-activate`. |
| espobase sites list | Seus sites hospedados e seus endereços. |
| espobase ai propose "<request>" | Um plano de mudança de esquema (SQL e risco) que você revisa e aplica no painel. |
| espobase open | O projeto vinculado no painel. |
| espobase whoami / logout | A conta conectada; sair (e revogar o login). |
Todo comando aceita --json para scripts e --project <ref> para usar outro projeto que não o vinculado.
Migrações
Mantenha seu esquema no seu repositório: escreva cada mudança como um arquivo SQL, revise como código e envie para um projeto pelo terminal ou pela CI.
npx espobase migration new create_dishes # write the SQL in espobase/migrations/20261005143000_create_dishes.sql npx espobase db push --dry-run # runs it, then rolls everything back npx espobase db push # applies it
- Os arquivos rodam em ordem de versão, uma vez cada. O Espobase registra a versão, o nome, o checksum, quem e quando; seu SQL fica no seu repositório.
- Cada arquivo roda em uma transação junto com o seu registro: é aplicado por inteiro ou não é aplicado. Se um falha, o envio para ali e mostra o arquivo e a linha.
- Não edite um arquivo depois de aplicado: escreva um novo.
db pushrecusa arquivos alterados e arquivos mais antigos que o último aplicado. - Tabelas novas têm a segurança em nível de linha ativada. Adicione as políticas delas no mesmo arquivo para que o seu app consiga acessá-las.
- Valem as regras do editor SQL: desenvolvedores podem alterar dados e esquema; políticas, GRANTs e outras mudanças de permissão precisam de um administrador. Instruções destrutivas (DROP, TRUNCATE, DELETE sem WHERE…) precisam de
--allow-destructivee de um administrador. - Enviar precisa da permissão Apply migrations (database:write): pedida ao entrar, ou escolhida ao criar um token para a CI. Na CI, adicione
--yes.
CI e servidores
Crie um token de acesso pessoal no painel (Configurações da conta › Desenvolvedor) com apenas os escopos de que o job precisa e passe-o como ESPOBASE_TOKEN:
ESPOBASE_TOKEN=espo_pat_… npx espobase gen types --project <ref> ESPOBASE_TOKEN=espo_pat_… npx espobase db push --yes --project <ref>
O que a CLI pode e não pode fazer
- Ela age como você, com a sua função, nos projetos que você pode acessar.
- Ele só altera um projeto com permissões explícitas:
db pushaplica seus arquivos de migração efunctions deploypublica edge functions edeploypublica sites hospedados. O resto do SQL é somente leitura, e as mudanças de esquema da IA são propostas que você aplica no painel. - Ela nunca busca senhas de banco de dados nem chaves de API.
- O login pelo navegador vale até você executar
espobase logoutou desconectá-lo em Configurações da conta › Desenvolvedor › Apps conectados. Os tokens são guardados de forma que só você possa lê-los.