Table of Contents
- HOW-TO: Getting Started with @quatrain/core-cli
- 1. Initializing a New Project
- 2. Generating the Bootloader Configuration
- 3. Creating Migrations
- 4. Local Development & Global CLI Setup
- A. Run on the Fly via Yarn Workspaces
- B. Setup a Global Command Alias (Recommended for Zsh)
- C. Install Locally-Built Folder Globally via NPM
- Documentation Guidelines
HOW-TO: Getting Started with @quatrain/core-cli
This guide explains how to leverage the core CLI to build and structure your Quatrain applications effortlessly.
1. Initializing a New Project
To start a new Quatrain project from scratch, use the scaffold command. This will generate a monorepo folder architecture ready to use.
npx @quatrain/core-cli scaffold MyProject
cd MyProject
yarn install
What it does:
- Creates a
package.jsonfor Yarn Workspaces. - Sets up alias paths in
tsconfig.json. - Creates placeholder directories for
apps,packages,data, andconfig.
2. Generating the Bootloader Configuration
The @quatrain/app bootloader requires a quatrain.json file to auto-instantiate the required adapters.
Run the interactive wizard from the root of your new project:
npx @quatrain/core-cli generate config
Answer the prompts to select your preferred Backend (e.g., PostgreSQL), Authentication (e.g., Supabase), Storage, and Queue systems.
Resulting quatrain.json:
The file will contain configurations mapping to environment variables:
{
"backend": {
"adapter": "PostgresAdapter",
"package": "@quatrain/backend-postgres",
"config": {
"host": "env(PG_HOST)",
"port": "env(PG_PORT)"
}
}
}
3. Creating Migrations
To safely upgrade the database schema, generate migration files directly from the CLI.
npx @quatrain/core-cli generate migration initialize_users
This generates migrations/20260427XXXXXX_initialize_users.ts. Open this file and fill in the up() and down() functions using the Quatrain Backend singleton.
4. Local Development & Global CLI Setup
When developing or modifying the CLI locally, you can run and test the tool in several ways:
A. Run on the Fly via Yarn Workspaces
From the root of the Core monorepo:
yarn workspace @quatrain/core-cli core <command>
# Example:
yarn workspace @quatrain/core-cli core deploy
B. Setup a Global Command Alias (Recommended for Zsh)
To use the core command directly from any directory without installing it globally, add an alias to your Zsh configuration (~/.zshrc):
echo 'alias core="node /Users/crapougnax/CODE/QUATRAIN/Core/packages/core-cli/bin/core.js"' >> ~/.zshrc
source ~/.zshrc
You can then run:
core deploy
C. Install Locally-Built Folder Globally via NPM
Alternatively, link the package to your global Node bin directory:
cd packages/core-cli
npm install -g .
Note
When modifying TypeScript source files, make sure to compile them with
yarn buildor keep the compiler in watch mode withyarn wbuildinside thepackages/core-clidirectory.
Documentation Guidelines
Recommendation: Ensure that all logs, commit messages, console outputs, and code comments are written in International English. This convention aligns with the official Quatrain standard to support a globally distributed engineering team.
Core Documentation
Foundations
Storage, Data & Cache
- backend
- backend-firestore
- backend-postgres
- backend-sqlite
- backend-migrations
- storage
- storage-firebase
- storage-s3
- storage-supabase
- storage-local
- cache
- cache-redis
Queue & Messaging
Auth & Cloud
- auth
- auth-firebase
- auth-supabase
- auth-oidc
- auth-pocketbase
- cloudwrapper
- cloudwrapper-firebase
- cloudwrapper-supabase