Start a project
DOCUMENTATION

Espobase CLI

Work with your projects from the terminal: link a folder to a project, generate TypeScript types, run read-only queries and check logs and usage. It needs Node.js 20 or later.

← All docs

Get started

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

Or install it once with npm install -g espobase and run espobase ….

Commands

espobase loginOpens your browser: sign in to Espobase and click Allow. Use --token espo_pat_… on servers.
espobase init [<ref>]Links this folder to a project, writes espobase.types.ts and prints your app's ESPOBASE_URL.
espobase projects listYour projects, per organization.
espobase projects create <name> --org <slug>A new project (its database is set up in a moment).
espobase link <ref> / unlinkLinks this folder to a project (.espobase/project.json, safe to commit).
espobase gen types [--out <file>]TypeScript types for createClient<Database>() in @espobase/client.
espobase db query "<sql>"Read-only SQL: SELECT, EXPLAIN, SHOW…
espobase migration new <name>A new SQL file in espobase/migrations, named by the current UTC time.
espobase migration listWhich migration files are applied, pending or changed.
espobase db push [--dry-run]Applies the pending migration files in order, each in one transaction. --dry-run checks them and rolls back.
espobase logs [--errors]Recent API requests: path, status, timing (never bodies or secrets).
espobase usage [--range 7d]Requests, bandwidth, database and file storage, AI usage.
espobase storage ls [<bucket>]Your buckets, or the files in one.
espobase deploy <folder> --site <address>Publishes a build folder to a hosted site and makes it live (needs the Deploy sites permission). `--message`, `--no-activate`.
espobase sites listYour hosted sites and their addresses.
espobase ai propose "<request>"A schema change plan (SQL and risk) you review and apply in the dashboard.
espobase openThe linked project in the dashboard.
espobase whoami / logoutThe signed-in account; sign out (and revoke the sign-in).

Every command takes --json for scripts and --project <ref> to use another project than the linked one.

Migrations

Keep your schema in your repository: write each change as a SQL file, review it like code, and push it to a project from your terminal or 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
  • Files run in version order, once each. Espobase records the version, name, checksum, who and when; your SQL stays in your repository.
  • Each file runs in one transaction with its record: it's applied completely or not at all. If one fails, the push stops there and shows the file and line.
  • Don't edit a file after it's applied: write a new one. db push refuses changed files and files older than the newest applied one.
  • New tables have row level security on. Add their policies in the same file so your app can reach them.
  • The SQL editor's rules apply: developers can change data and schema; policies, grants and other permission changes need an admin. Destructive statements (DROP, TRUNCATE, DELETE without WHERE…) need --allow-destructive and an admin.
  • Pushing needs the Apply migrations permission (database:write): asked for at sign-in, or chosen when you create a token for CI. In CI, add --yes.

CI and servers

Create a personal access token in the dashboard (Account settings › Developer) with only the scopes the job needs, and pass it as ESPOBASE_TOKEN:

ESPOBASE_TOKEN=espo_pat_… npx espobase gen types --project <ref>
ESPOBASE_TOKEN=espo_pat_… npx espobase db push --yes --project <ref>

What the CLI can and can't do

  • It acts as you, with your role, on the projects you can reach.
  • It changes a project only with explicit permissions: db push applies your migration files and functions deploy deploys edge functions, and deploy publishes hosted sites. Other SQL is read-only, and AI schema changes are proposals you apply in the dashboard.
  • It never fetches database passwords or API keys.
  • Browser sign-in lasts until you run espobase logout or disconnect it in Account settings › Developer › Connected apps. Tokens are stored readable only by you.