Documentation

CrescoDB gives you an instant local backend: a database, an auto-generated REST API, auth with roles, file storage, realtime subscriptions, an admin dashboard, and AI that designs schemas and writes code.

Install

CrescoDB is a CLI. With Node installed:

$ npm install -g crescodb # or: npx crescodb

Quickstart

$ cresco init # scaffold an EMPTY project (schema.cresco, config.json, cresco.db) $ cresco dev # REST API on :3000 + the dashboard $ cresco create auth # write full auth code — register.js, login.js, middleware

A new project starts empty — add tables with cresco create, the AI assistant, or the dashboard's schema editor. (Want demo tables? cresco init --starter.) Open the dashboard at http://localhost:3000/studio to browse data, edit schema, run SQL, upload files, and watch changes live.

CLI reference

  • cresco login — sign in to your CrescoDB account · logout · whoami
  • cresco init — scaffold a new (empty) project · --starter for demo tables
  • cresco dev — run the API server + dashboard (-p to set the port)
  • cresco start — the production server: API + auth only, no admin surfaces
  • cresco generate — sync schema.cresco → tables
  • cresco ai "…" — natural language → schema
  • cresco create <feature> — write a feature as full editable code (auth, blog, payments) · --express / --next
  • cresco add <module> — install a managed module: bundled or from the registry
  • cresco publish — publish a module from this folder to the registry
  • cresco orgs — list your teams · cresco org create <slug> · org add <slug> <email> · org members <slug>
  • cresco link — share this project with your team · cresco projects (list) · cresco open <slug> (open a teammate's)
  • cresco install <pkg> — add npm packages · cresco audit · cresco fund

Schema

Your data lives in schema.cresco — JSON models with typed fields (string, text, number, boolean, uuid, date, json). It's the single source of truth; the dashboard and AI edit the same file.

Databases (SQLite · PostgreSQL · MySQL)

SQLite is the zero-config default — perfect for local development and read-heavy apps, with nothing to install. Pick a different engine from dashboard → Settings → Connection → Database engine (or set dialect in config.json). Your schema.cresco and the entire REST API stay identical across engines.

PostgreSQL — two ways, no DBA required

  • Zero-config local Postgres. Choose PostgreSQL and leave the connection blank — CrescoDB downloads and runs a real Postgres server for you (data kept in .cresco/pgdata, so it persists). No install, no credentials, just like SQLite. cresco dev prints the local port so you can also connect pgAdmin/psql to it.
  • Your own / hosted server. Already have Postgres — a local install, docker run postgres, or a managed host like Railway, Neon, or Supabase? Paste its connection string and CrescoDB connects to that instead (it honors sslmode=require for managed hosts). This is also how a whole team shares one live database.

MySQL — bring your own

Choose MySQL and provide a connection string to a MySQL server (a local install or one line of Docker: docker run -e MYSQL_ROOT_PASSWORD=pass -p 3306:3306 -d mysql).

// config.json — connect to your own / a hosted server { "dialect": "postgres", "connection": "postgres://user:pass@host:5432/dbname?sslmode=require" } // …or leave "connection" off for a managed local Postgres: { "dialect": "postgres" }

Switching engines & your data

  • Your first switch is safe. Moving off the default SQLite carries your schema over and leaves your existing cresco.db file untouched — nothing is deleted.
  • Switching again later doesn't migrate data automatically (engines store data differently). To carry data across a later switch: Export your project as .sql (Settings → Connection), switch, then Import it into the new engine.
  • After changing the engine, restart cresco dev to connect.

REST API

Every model gets full CRUD automatically — GET/POST/PUT/PATCH/DELETE /:model, plus /:model/:id, bulk insert, and ?limit/?offset/?where. No routing to write.

Auth & roles

Two ways to get auth, both real:

  • cresco create auth — writes complete auth code you own (register.js, login.js, middleware.js, jwt.js) wired to your project database. Read it, edit it, extend it.
  • cresco add auth — enables the built-in managed auth: JWT register/login/me plus role-based access control — roles guest · user · mod · admin and a per-table access policy enforced on every request. Models can also declare a rowOwner column for per-row security: users only ever see and touch their own rows.

Manage users and policies from the dashboard's Users page either way.

Scaffolds — cresco create

Writes a feature into your project as full, editable code — real files, not a package. Models merge into your schema, endpoints go live on cresco dev immediately, and every file is yours to change.

$ cresco create auth # plain Node — wired straight into your project $ cresco create blog --express # code for your own Express app (uses cresco-js) $ cresco create payments --next # Next.js App Router route handlers + pages
  • auth — register / login / me, JWT + scrypt, middleware for your own routes
  • blog — posts + comments tables, slugged public feed, comment API (and server-rendered pages on --next)
  • payments — Paystack + Flutterwave checkout & verify, recorded in a payments table. No keys yet? It runs in dev mode (instant fake success) so you can build the flow first.

Modules

cresco add installs managed, database-aware modules — they merge models into your schema, drop in code, and record a migration. Use create when you want to own the code; use add for managed installs and community modules from the registry.

File storage

Every project has bucket-based file storage at /storage — uploads, folders, public or private buckets, and a file browser in the dashboard. Locally files live in .cresco/storage; in production point config.storage at any S3-compatible store (AWS S3, Cloudflare R2).

// with the SDK await cresco.storage('avatars').upload('me/photo.png', file); const url = cresco.storage('avatars').url('me/photo.png'); // for <img src> # or raw HTTP $ curl -X PUT :3000/storage/avatars/me/photo.png --data-binary @photo.png

Public buckets serve files at a plain URL; private buckets require auth. Toggle visibility from the dashboard's Storage page.

Realtime

Subscribe to live row changes — every create, update and delete streams to connected clients over SSE, with table access rules and per-row security respected. The dashboard's Realtime page shows the live feed.

const sub = cresco.channel('posts') .on('created', (e) => console.log('new post', e.data)) .on('*', (e) => render(e)) .subscribe(); // later: sub.unsubscribe()

JS SDK — cresco-js

A zero-dependency client for browsers and Node 18+: auth, fluent CRUD, storage, and realtime in one import.

import { createClient } from 'cresco-js'; const cresco = createClient('http://localhost:3000'); await cresco.auth.login('me@x.dev', 'secret1'); const posts = await cresco.from('posts').eq('published', true).limit(10); await cresco.from('posts').create({ title: 'Hello' });

Production — cresco start

The production server serves only your API, auth, storage, realtime and custom routes — every admin surface (SQL editor, schema DDL, AI, dashboard) is absent, not just disabled. Configure with env vars: DATABASE_URL, PORT, CRESCO_AUTH_SECRET, CRESCO_CORS_ORIGIN; pending migrations run at boot. Server-to-server callers can use the project API key for full access.

Languages

Your app can be written in any language — it just talks to the REST API over HTTP (the CLI needs Node installed to run, like Docker for a database). Scaffold code is currently provided for:

  • Node — available now (auth, blog, payments), plus Express and Next.js variants
  • Python, Go, PHP — on the way

Accounts & sign-in

A CrescoDB account unlocks the hosted features — the AI coding agent, cloud backups, publishing, and shared projects. The dashboard requires a signed-in account; the CLI and API work offline once you're set up.

Private beta: CrescoDB is currently invite-only. Creating an account (email/password or GitHub/Google) requires a beta key issued for your email — request one. Beta accounts get Pro-level features while the beta runs.

$ cresco login # opens the browser to approve a device code $ cresco whoami # show the signed-in account + plan $ cresco logout # sign out

cresco login uses a device-authorization flow: it shows a short code, opens crescodb.com/activate, and once you approve it (while signed in) the CLI is connected. The token is stored in ~/.cresco/config.json. Paid features are checked against your plan on the server.

Publishing modules

Anyone on a paid plan can publish modules to the registry. Describe the module with a cresco.module.json in its folder, then run cresco publish:

// cresco.module.json { "name": "my-auth", "version": "1.0.0", "description": "Drop-in auth", "visibility": "public", // or "private" (Team plan) "models": [ /* merged into schema.cresco */ ], "code": { "folder": "auth", "languages": ["node"] } }

Install any published module with cresco add <name> — it merges the models and drops the code, just like a bundled module. Public modules install for anyone; private (scoped @org/name) and paid modules are gated to entitled accounts.

Teams

An org (team) is a shared workspace with its own private module scope. Create one and the slug becomes your @scope; members can install the org's private modules.

$ cresco org create acme # you become the owner $ cresco org add acme jane@acme.dev # add a member (--admin for admin) $ cresco org members acme # list members $ cresco orgs # list your orgs

Publish a private module to the org with a scoped name (@acme/billing) — only admins/owners can publish, and any member can cresco add @acme/billing. A private registry requires a Team plan.

Shared live projects

Beyond modules, a whole project can be shared so teammates anywhere work against the same live database. Point the project at a shared Postgres/MySQL (a Railway/Neon/Supabase or your own server — Settings → Connection), then:

$ cresco link --org acme # register this project (shared DB + schema) to the team $ cresco projects # list projects you can open $ cresco open shop # a teammate pulls it into a folder… $ cd shop && cresco dev # …and is on the same live data

Anyone in the org (signed in to their own CrescoDB account, anywhere in the world) can cresco open it; access is checked server-side on every open. The shared connection lives in the project's config — local SQLite/embedded projects share their schema but not their data, so use a shared server for a true shared-live project. Re-running cresco link syncs the latest schema.

Plans & billing

Local development is free forever. Plans differ by capability, not just AI limits:

  • Free — everything local, AI chat, 1 cloud project. No agent, no cloud backups.
  • Pro — the AI coding agent with smart model routing, 25 cloud backups, 10 cloud projects, registry publishing.
  • Team (per seat) — create team workspaces & shared live projects, the private @org registry, 100 backups, 50 projects. (Pro users can join a team; creating one needs Team.)
  • Enterprise — our most capable model first on every big task, unlimited backups & projects, dedicated support.

AI usage is measured in Cresco tokens. Every plan includes a monthly amount (see pricing); each request deducts tokens based on its size — small requests use a few, large agent tasks use more. Usage also has daily and weekly ceilings within the month. Model selection is automatic. Your token balance is shown in the dashboard.

Billing is managed from dashboard → Settings → Billing. Payments are processed by Paystack (Naira) and Flutterwave (international cards); pick your currency at checkout.