CLI de Espobase
Trabaja con tus proyectos desde la terminal: vincula una carpeta a un proyecto, genera tipos de TypeScript, ejecuta consultas de solo lectura y revisa registros y uso. Requiere Node.js 20 o posterior.
Primeros pasos
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
O instálala una vez con npm install -g espobase y ejecuta espobase ….
Comandos
| espobase login | Abre tu navegador: inicia sesión en Espobase y autoriza el acceso. En servidores, usa --token espo_pat_…. |
| espobase init [<ref>] | Vincula esta carpeta a un proyecto, escribe espobase.types.ts y muestra el ESPOBASE_URL de tu app. |
| espobase projects list | Tus proyectos, por organización. |
| espobase projects create <name> --org <slug> | Un proyecto nuevo (su base de datos queda lista en un momento). |
| espobase link <ref> / unlink | Vincula esta carpeta a un proyecto (.espobase/project.json, puedes subirlo a tu repositorio). |
| espobase gen types [--out <file>] | Tipos de TypeScript para createClient<Database>() en @espobase/client. |
| espobase db query "<sql>" | SQL de solo lectura: SELECT, EXPLAIN, SHOW… |
| espobase migration new <name> | Un archivo SQL nuevo en espobase/migrations, con la hora UTC actual en el nombre. |
| espobase migration list | Qué archivos de migración están aplicados, pendientes o modificados. |
| espobase db push [--dry-run] | Aplica en orden los archivos de migración pendientes, cada uno en una transacción. --dry-run los comprueba y deshace todo. |
| espobase logs [--errors] | Solicitudes recientes a la API: ruta, estado, tiempos (nunca cuerpos ni secretos). |
| espobase usage [--range 7d] | Solicitudes, ancho de banda, almacenamiento de base de datos y de archivos, uso de IA. |
| espobase storage ls [<bucket>] | Tus buckets, o los archivos de uno de ellos. |
| espobase deploy <carpeta> --site <dirección> | Publica una carpeta de compilación en un sitio alojado y la activa (requiere el permiso Desplegar sitios). `--message`, `--no-activate`. |
| espobase sites list | Tus sitios alojados y sus direcciones. |
| espobase ai propose "<request>" | Un plan de cambio de esquema (SQL y riesgo) que revisas y aplicas en el panel. |
| espobase open | El proyecto vinculado, en el panel. |
| espobase whoami / logout | La cuenta con la que iniciaste sesión; cierra sesión (y revoca el acceso). |
Todos los comandos aceptan --json para scripts y --project <ref> para usar un proyecto distinto del vinculado.
Migraciones
Guarda tu esquema en tu repositorio: escribe cada cambio como un archivo SQL, revísalo como el código y envíalo a un proyecto desde tu terminal o tu 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
- Los archivos se ejecutan en orden de versión, una vez cada uno. Espobase registra la versión, el nombre, el checksum, quién y cuándo; tu SQL se queda en tu repositorio.
- Cada archivo se ejecuta en una transacción junto con su registro: se aplica entero o nada. Si uno falla, el envío se detiene ahí e indica el archivo y la línea.
- No edites un archivo después de aplicarlo: escribe uno nuevo.
db pushrechaza los archivos modificados y los que son anteriores al último aplicado. - Las tablas nuevas tienen la seguridad a nivel de fila activada. Añade sus políticas en el mismo archivo para que tu app pueda acceder a ellas.
- Se aplican las reglas del editor SQL: los desarrolladores pueden cambiar datos y esquema; las políticas, los permisos (GRANT) y otros cambios de permisos necesitan un administrador. Las instrucciones destructivas (DROP, TRUNCATE, DELETE sin WHERE…) necesitan
--allow-destructivey un administrador. - Para enviar hace falta el permiso Apply migrations (database:write): se pide al iniciar sesión, o se elige al crear un token para CI. En CI, añade
--yes.
CI y servidores
Crea un token de acceso personal en el panel (Configuración de la cuenta › Desarrollador) solo con los permisos que necesita la tarea, y pásalo como ESPOBASE_TOKEN:
ESPOBASE_TOKEN=espo_pat_… npx espobase gen types --project <ref> ESPOBASE_TOKEN=espo_pat_… npx espobase db push --yes --project <ref>
Lo que la CLI puede y no puede hacer
- Actúa como tú, con tu rol, en los proyectos a los que tienes acceso.
- Solo cambia un proyecto con permisos explícitos:
db pushaplica tus archivos de migración yfunctions deploypublica edge functions ydeploypublica sitios alojados. El resto del SQL es de solo lectura, y los cambios de esquema de la IA son propuestas que aplicas en el panel. - Nunca obtiene contraseñas de base de datos ni claves de API.
- El inicio de sesión desde el navegador dura hasta que ejecutes
espobase logouto lo desconectes en Configuración de la cuenta › Desarrollador › Apps conectadas. Los tokens se guardan de modo que solo tú puedas leerlos.