CLI Overview

Open Saasframe bundles CLI commands for project setup, tenant administration, and module scaffolding. Top-level helpers are exposed as Yarn scripts (yarn initialize, yarn db:generate, …) while module-specific utilities live under the umbrella command:

yarn saasframe <module> <command> [options]

Run yarn saasframe --help to list modules and yarn saasframe <module> --help to drill in.

Workflow Cheat Sheet

• Bootstrap & Database
  • yarn initialize – full app bootstrap with optional reinstall mode (wraps saasframe init).
  • yarn db:generate – per-module migration diffing (alias for saasframe db generate).
  • yarn db:migrate – apply migrations and refresh generated metadata.
  • yarn db:greenfield – destructive reset that regenerates a clean schema.
• Development Runtime
  • yarn dev – start the compact development runtime with splash-based startup progress on the default local backend port, plus ready-state splash actions such as coding-tool launchers and standalone GitHub publish helpers when enabled.
  • yarn dev:classic – start the legacy raw passthrough runtime with no splash screen.
  • yarn dev:verbose – start the same runtime in raw passthrough mode for debugging.
  • yarn dev:greenfield:classic – run the greenfield boot flow with raw passthrough output and no splash screen.
  • yarn dev:ephemeral – start a dev server on a free port, open browser automatically, and register active instances in .ai/dev-ephemeral-envs.json.
  • yarn dev:ephemeral:classic – run the ephemeral flow with raw passthrough output and no splash screen.
  • Database name override (optional, additive): every dev/setup command above accepts --database-name[=<name>] to rewrite the database segment of DATABASE_URL for the run. Examples: yarn dev --database-name=client_a (explicit), yarn dev --database-name (derive from process.cwd()), yarn dev --database-name=temp --no-update-env (current run only). Without the flag, behavior is unchanged. See the monorepo and standalone installation guides for the full walkthrough.
• Code Generation
  • saasframe generate or saasframe generate all – run all generators (entity IDs, registry, entities, DI, API client).
  • saasframe generate entity-ids – generate entity ID mappings.
  • saasframe generate registry – generate module registry.
  • saasframe generate entities – generate ORM entity aggregation.
  • saasframe generate di – generate dependency injection registrars.
  • saasframe generate api-client – generate typed API client.
• Database
  • saasframe db generate – generate per-module migrations.
  • saasframe db migrate – apply pending migrations.
  • saasframe db greenfield --yes – destructive reset and regenerate schema.
• Deployment
  • saasframe deploy railway – provision or update a Railway project using Git or local source, with managed PostgreSQL, Redis, an optional worker, and tracked deployment state.
• Auth module
  • saasframe auth seed-roles
  • saasframe auth sync-role-acls
  • saasframe auth setup
  • saasframe auth add-user
  • saasframe auth set-password
  • saasframe auth list-orgs
  • saasframe auth list-users
  • saasframe auth list-tenants
• Security
  • saasframe api_keys add – mint scoped API keys for automations.
• Events & Queue
  • saasframe events emit <event> [payload] [-p] – emit an event (optionally persistent).
  • saasframe events clear – clear the events queue.
  • saasframe queue worker <name> – run a queue worker (e.g., queue worker events).
  • saasframe queue status <name> – show queue job counts.
  • saasframe queue clear <name> – clear all jobs from a queue.
• Scaffolding
  • saasframe scaffold module <name> – create a new module skeleton.
  • saasframe scaffold entity – interactive entity creation wizard.
  • saasframe scaffold crud <module> <Entity> [route] – generate CRUD route for an entity.
• Entities
  • saasframe entities install
  • saasframe entities decrypt-database
• Configs module
  • saasframe configs cache – inspect cache segments and purge by segment, tag, key, identifier token, pattern, or structural navigation scope.
• Official Modules
  • saasframe module add <packageSpec> – install and register an official @saasframe/* module package.
  • saasframe module add <packageSpec> --eject – copy module source into src/modules/ for local ownership.
  • saasframe module enable <packageName> – register an already-installed official module package (no dependency install).
  • saasframe module enable <packageName> --eject – copy an already-installed package into src/modules/ and enable it as @app.
  • saasframe module eject <moduleId> – alias for saasframe eject <moduleId>.
• Module Ejection
  • saasframe eject --list – list modules available for ejection.
  • saasframe eject <moduleId> – copy a core module into your local src/modules/ for full customization.
• Integration Testing
  • yarn test:integration:ephemeral – run Playwright tests in disposable app+DB containers.
  • yarn test:integration:ephemeral:interactive – keep one disposable app+DB running and choose tests from an interactive menu.
  • yarn test:integration:ephemeral:start – start disposable app+DB only for QA/MCP exploration.

Each linked page provides usage syntax, option breakdowns, sample output, and troubleshooting notes so you can copy commands directly into your terminal.