@promakeai/cli

Full-stack app CLI. promake scaffolds a modular React frontend (shadcn/ui-style, code copied directly into your project for full ownership) and wires it to a managed backend: database, auth, functions, storage, email, realtime, and cron. You create a project, add feature modules incrementally, and manage the backend manifest (backend.json) from the same CLI.

Two surfaces:

• Frontend / modules - create, add, remove, sync, theme, list, info, seo copy registry modules and theme tokens into the project.
• Managed backend (BaaS) - manifest, functions, emails, storage, cron, realtime declare backend resources in backend.json and push/operate them against the tenant backend pod.

Documentation

Full guide: docs/index.md. Backend command groups: manifest, functions, emails, storage, cron, realtime.

You can also get an always-up-to-date guide straight from the CLI:

promake usage              # full CLI guide
promake usage <command>    # rich per-command guide (purpose, flags, examples, related)
promake usage --json       # machine-readable catalog (for agents)

Quick Start

# Install globally
npm install -g @promakeai/cli

# Create a project
promake create my-app --preset ecommerce --pm bun

# In an existing project, map its full state first (recommended)
promake discover            # human-readable
promake discover --json     # for agents

# Add modules
promake add hero product-card

# Theme customization
promake theme --preset blue --radius medium

# Health check (Environment -> Integrations -> Frontend)
promake doctor

Commands

Frontend / modules

| Command | Description | |---------|-------------| | promake create <name> | Scaffold a new full-stack project (frontend + backend.json; generates admin token) | | promake add <items...> | Add modules, components, or pages | | promake remove <modules...> | Remove installed modules (alias rm) | | promake sync | Install missing modules from promake.json | | promake theme | Configure theme (colors, radius, shadow, fonts) | | promake list | Browse available modules (alias ls) | | promake info <module> | Detailed info about a module | | promake seo | Sync SEO meta tags from constants.json to index.html |

Discovery + health

| Command | Description | |---------|-------------| | promake discover | Map project state: stack, modules, backend, database, config files (--json for agents). First command in an existing project | | promake usage [command\|module] | Full CLI guide, a rich per-command guide, or a module's docs | | promake doctor | Health check: Environment, Integrations, Frontend (--json for CI) | | promake init | Initialize promake.json | | promake zip / promake unzip | Archive utilities |

Managed backend (backend.json + tenant pod)

| Command | Description | |---------|-------------| | promake manifest validate | Validate all config files locally (backend.json, promake.json, constants.json, schema.json; no push) | | promake manifest push | Validate, then push backend.json + bodies to the tenant backend pod | | promake manifest show | Show the active manifest on the pod | | promake functions <create\|update\|delete\|list\|get\|invoke\|logs\|validate> | Manage functions/ (Deno) and their backend.json entries | | promake emails template <new\|list\|get\|send\|delete> | Manage emails/ HTML templates and their backend.json entries | | promake storage <upload\|download\|list\|delete> | Tenant storage objects (presigned S3) | | promake cron <add\|remove\|list\|run> | Author/list/fire scheduled functions in backend.json crons[] | | promake realtime <enable\|disable\|list> | Manage realtime tables in backend.json realtime.tables |

No command uses an interactive spinner; output renders once.

Data Layer

Projects generated by Promake include @promakeai/dbreact with a JSON schema (src/db/schema.json) and support for both SQLite and REST API modes. Use @/db hooks (useDbList, useDbGet, etc.) for data access.

Database Modes

• SQLite (default) - Prebuilt database.db loaded via sql.js WASM in the browser
• REST API - Connects to the tenant backend with automatic Bearer auth for logged-in users

Auth Integration

When REST API mode is active, the template's AppDbProvider reads auth tokens from localStorage (where auth-core's Zustand store persists under the "auth-storage" key). No direct dependency on auth-core module code.

Admin Token

During promake create, a UUID admin token is generated and written to .env as VITE_DB_ADMIN_TOKEN. This token is used by @promakeai/dbcli for authenticated REST API access when managing the project's database.

Schema Permissions

All template tables include $permissions metadata for role-based access control:

"$permissions": {
  "anon": ["read"],
  "user": ["read", "create", "update:own", "delete:own"],
  "admin": ["read", "create", "update", "delete"]
}

Roles: anon, user, admin. Actions: read, create, update, delete. The read, update, and delete verbs may add the :own qualifier (e.g. read:own) to scope the action to rows the caller owns. create:own is NOT valid (a row has no owner until it exists). manifest validate enforces this.

Backend Manifest (backend.json)

backend.json sits next to promake.json and declares the project's managed-backend resources. The CLI edits it locally; promake manifest push validates it and applies it to the tenant backend pod.

{
  "version": 1,
  "functions": { "checkout": { "roles": ["user", "admin"] } },
  "emails": { "templates": [{ "name": "welcome", "subject": "Welcome" }] },
  "crons": [{ "name": "digest", "schedule": "0 9 * * *", "function": "daily-digest" }],
  "realtime": { "tables": ["messages"] }
}

Function handlers live in functions/ (Deno) and are typed against the generated functions.d.ts. Each handler receives (req, env, ctx) where env is { db, storage, emails } (env.emails sends with admin authority) and ctx.user is { id, role } | null. env.emails.send accepts an attachments array ({ filename, content, contentType? }, where content is a URL, base64 string, or raw bytes). Contact forms route to the tenant backend's POST /contact through the template's useFormSubmit hook, which persists the submission and sends the customer + owner email (with attachments) server-side. See docs/functions.md.

Available Presets

| Preset | Description | |--------|-------------| | ecommerce | Full e-commerce with products, categories, cart | | blog | Blog with posts, categories, comments | | portfolio | Portfolio with projects and sections | | empty | Minimal template with no pre-installed modules |

Development

# Install dependencies
bun install

# Run from source
bun run dev

# Build (CLI + registry)
bun run build

# Test
bun test

# Type check
bun run typecheck

# Validate the bundled template (strict: lint/typecheck/build clean + configs valid + no drift)
bun run validate:template

validate:template is enforced by the CLI build, prepublishOnly, and CI.

Related Packages

• @promakeai/dbreact - React database hooks (used in template)
• @promakeai/dbcli - Database CLI tool
• @promakeai/orm - Core ORM + manifest validator

License

MIT