@objectql/cli

Command Line Interface for ObjectQL - A comprehensive toolkit for building, managing, and deploying ObjectQL applications.

Installation

npm install -g @objectql/cli
# OR
pnpm add -D @objectql/cli

Commands

Lifecycle (Delegated to @objectstack/cli)

The following commands are now delegated to @objectstack/cli:

• objectql init → objectstack create
• objectql dev → objectstack dev
• objectql start → objectstack serve
• objectql doctor → objectstack doctor

You can use either objectstack or the short alias os:

npx objectstack dev
npx os serve
npx objectstack doctor
npx objectstack create

Metadata & Tooling (This CLI)

This CLI focuses on metadata scaffolding, type generation, database workflows, i18n, and local tooling:

• generate, new, db push, db pull, migrate
• i18n extract, i18n init, i18n validate
• lint, format, repl, test, build

Metadata Generation

new <type> <name>

Generate a new metadata file with boilerplate code.

# Create a new object definition
objectql new object users

# Create a view
objectql new view user_list

# Create a form
objectql new form user_edit

# Create in a specific directory
objectql new object products --dir ./src/modules/catalog

Supported Types:

• object - Object/Entity definition
• view - Data view configuration
• form - Form layout
• page - Page definition
• action - Custom action (generates .yml + .ts)
• hook - Lifecycle hook (generates .yml + .ts)
• permission - Permission rules
• validation - Validation rules
• workflow - Workflow automation
• report - Report definition
• menu - Menu configuration
• data - Sample data

Options:

• -d, --dir <path> - Output directory [default: "."]

TypeScript Code Generation

generate (alias: g)

Generate TypeScript interfaces from your object.yml definitions.

# Generate types from current directory
objectql generate

# Specify source and output directories
objectql generate -s src -o src/generated

# Generate from specific path
objectql generate --source ./metadata --output ./types

Options:

• -s, --source <path> - Source directory containing *.object.yml [default: "."]
• -o, --output <path> - Output directory for generated types [default: "./src/generated"]

Internationalization (i18n)

i18n extract

Extract translatable strings from metadata files and create translation files.

# Extract to default location (./src/i18n/en)
objectql i18n extract

# Extract for specific language
objectql i18n extract --lang zh-CN

# Custom source and output directories
objectql i18n extract -s ./metadata -o ./translations --lang fr

Options:

• -s, --source <path> - Source directory [default: "."]
• -o, --output <path> - Output directory [default: "./src/i18n"]
• -l, --lang <lang> - Language code [default: "en"]

i18n init <lang>

Initialize i18n structure for a new language.

# Initialize for Chinese (Simplified)
objectql i18n init zh-CN

# Initialize for French
objectql i18n init fr

# Custom base directory
objectql i18n init es --base-dir ./translations

Options:

• -b, --base-dir <path> - Base i18n directory [default: "./src/i18n"]

i18n validate <lang>

Validate translation completeness against base language.

# Validate Chinese translations against English
objectql i18n validate zh-CN

# Use custom base language
objectql i18n validate fr --base-lang en

# Custom directory
objectql i18n validate es --base-dir ./translations

Options:

• -b, --base-dir <path> - Base i18n directory [default: "./src/i18n"]
• --base-lang <lang> - Base language to compare against [default: "en"]

Database Migrations

migrate

Run pending database migrations.

# Run all pending migrations
objectql migrate

# Specify custom config file
objectql migrate --config ./config/objectstack.config.ts

# Custom migrations directory
objectql migrate --dir ./db/migrations

Options:

• -c, --config <path> - Path to objectstack.config.ts/js
• -d, --dir <path> - Migrations directory [default: "./migrations"]

migrate create <name>

Create a new migration file.

# Create a new migration
objectql migrate create add_status_field

# Custom directory
objectql migrate create init_schema --dir ./db/migrations

Options:

• -d, --dir <path> - Migrations directory [default: "./migrations"]

migrate status

Show migration status (pending vs. completed).

# Show migration status
objectql migrate status

# With custom config
objectql migrate status --config ./config/objectstack.config.ts

Options:

• -c, --config <path> - Path to objectstack.config.ts/js
• -d, --dir <path> - Migrations directory [default: "./migrations"]

sync

Introspect an existing SQL database and generate ObjectQL .object.yml files from the database schema. This is useful for:

• Connecting to an existing/legacy database
• Reverse-engineering database schema to ObjectQL metadata
• Bootstrapping a new ObjectQL project from an existing database

# Sync all tables from the database
objectql sync

# Sync specific tables only
objectql sync --tables users posts comments

# Custom output directory
objectql sync --output ./src/metadata/objects

# Overwrite existing files
objectql sync --force

# With custom config file
objectql sync --config ./config/objectstack.config.ts

Options:

• -c, --config <path> - Path to objectstack.config.ts/js
• -o, --output <path> - Output directory for .object.yml files [default: "./src/objects"]
• -t, --tables <tables...> - Specific tables to sync (default: all tables)
• -f, --force - Overwrite existing .object.yml files

Features:

• Automatically detects table structure (columns, data types, constraints)
• Maps SQL types to appropriate ObjectQL field types
• Identifies foreign keys and converts them to lookup relationships
• Generates human-readable labels from table/column names
• Preserves field constraints (required, unique, maxLength)
• Skips system fields (id, created_at, updated_at) as they're automatic in ObjectQL

Example:

Given a database with this table structure:

CREATE TABLE users (
    id VARCHAR PRIMARY KEY,
    username VARCHAR UNIQUE NOT NULL,
    email VARCHAR NOT NULL,
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

Running objectql sync generates:

# users.object.yml
name: users
label: Users
fields:
  username:
    type: text
    label: Username
    required: true
    unique: true
  email:
    type: text
    label: Email
    required: true
  is_active:
    type: boolean
    label: Is Active
    defaultValue: true

Development Tools

dev

Development server is delegated to @objectstack/cli:

npx objectstack dev
# or
npx os dev

start

Production server is delegated to @objectstack/cli:

npx objectstack serve
# or
npx os serve

build (alias: b)

Build project and prepare for production deployment. Validates metadata, generates TypeScript types, and copies files to dist folder.

# Build project
objectql build

# Build with custom output directory
objectql build --output ./build

# Build without type generation
objectql build --no-types

# Build without validation
objectql build --no-validate

Options:

• -d, --dir <path> - Source directory [default: "."]
• -o, --output <path> - Output directory [default: "./dist"]
• --no-types - Skip TypeScript type generation
• --no-validate - Skip metadata validation

Build Steps:

1. Validates all metadata files
2. Generates TypeScript type definitions (if enabled)
3. Copies all metadata files (.yml) to dist folder

test (alias: t)

Run tests for the ObjectQL project. Automatically detects and runs Jest tests if configured.

# Run all tests
objectql test

# Run tests in watch mode
objectql test --watch

# Run tests with coverage report
objectql test --coverage

# Specify project directory
objectql test --dir ./src

Options:

• -d, --dir <path> - Project directory [default: "."]
• -w, --watch - Watch mode (re-run tests on file changes)
• --coverage - Generate coverage report

Requirements:

• Jest must be installed and configured in package.json
• Falls back to npm test if Jest is not detected

lint (alias: l)

Validate metadata files for correctness and best practices.

# Lint all metadata files
objectql lint

# Lint specific directory
objectql lint --dir ./src/objects

# Auto-fix issues (future feature)
objectql lint --fix

Options:

• -d, --dir <path> - Directory to lint [default: "."]
• --fix - Automatically fix issues (future feature)

Validation Rules:

• Object and field names must be lowercase with underscores
• All objects should have labels
• All fields should have labels
• No empty objects (objects must have at least one field)

format (alias: fmt)

Format metadata files using Prettier for consistent styling.

# Format all YAML files
objectql format

# Format specific directory
objectql format --dir ./src

# Check formatting without modifying files
objectql format --check

Options:

• -d, --dir <path> - Directory to format [default: "."]
• --check - Check if files are formatted without modifying them

Formatting Rules:

• Uses Prettier with YAML parser
• Print width: 80 characters
• Tab width: 2 spaces
• Single quotes for strings

serve

Production server is delegated to @objectstack/cli:

npx objectstack serve
# or
npx os serve

• -d, --dir <path> - Directory containing schema [default: "."]

repl (alias: r)

Start an interactive shell to query your data.

# Start REPL
objectql repl

# Use custom config
objectql repl --config ./objectstack.config.ts

Options:

• -c, --config <path> - Path to objectstack.config.ts/js

Example REPL session:

objectql> await tasks.find()
objectql> await tasks.insert({ name: 'New Task', status: 'open' })
objectql> await tasks.update({ _id: '123' }, { status: 'completed' })

Typical Workflows

Starting a New Project

# 1. Create project
npx objectstack create

# 2. Navigate to project
cd my-app

# 3. Install dependencies (if skipped)
pnpm install

# 4. Start development
npx objectstack dev

Adding New Functionality

# 1. Create object definition
objectql new object products

# 2. Edit the generated file: products.object.yml

# 3. Generate TypeScript types
objectql generate

# 4. Add translations
objectql i18n extract --lang en
objectql i18n init zh-CN
objectql i18n extract --lang zh-CN

# 5. Test in REPL
objectql repl
> await products.find()

Managing Translations

# 1. Initialize new language
objectql i18n init zh-CN

# 2. Extract all translatable strings
objectql i18n extract --lang zh-CN

# 3. Translate the JSON files in src/i18n/zh-CN/

# 4. Validate completeness
objectql i18n validate zh-CN

Database Migrations

# 1. Create migration
objectql migrate create add_priority_field

# 2. Edit migration file in migrations/

# 3. Check status
objectql migrate status

# 4. Run migrations
objectql migrate

Configuration File

Most commands expect an objectstack.config.ts or objectstack.config.js file in your project root:

// objectstack.config.ts
import { ObjectQL } from '@objectql/core';
import { SqlDriver } from '@objectql/driver-sql';
import { ObjectLoader } from '@objectql/platform-node';
import * as path from 'path';

const app = new ObjectQL({
    datasources: {
        default: new SqlDriver({
            client: 'sqlite3',
            connection: {
                filename: path.join(__dirname, 'dev.sqlite3')
            },
            useNullAsDefault: true
        })
    }
});

const loader = new ObjectLoader(app.metadata);
loader.load(path.join(__dirname, 'src'));

export default app;

Environment Variables

Some commands support environment variables for configuration:

• OBJECTQL_CONFIG - Path to config file
• OBJECTQL_DB_URL - Database connection string

Getting Help

# Show all commands
objectql --help

# Show help for specific command
objectql generate --help
objectql i18n extract --help
objectql migrate --help

# ObjectStack CLI lifecycle help
objectstack --help

License

MIT