Skip to content

README.md

Latest commit

 

History

History
785 lines (555 loc) · 17.8 KB

README.md

File metadata and controls

785 lines (555 loc) · 17.8 KB

@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

AI-Powered Features

The ai command provides AI-powered application generation and assistance. By default, it starts in interactive conversational mode for the best experience.

Interactive Mode (Default)

Simply type objectql ai to start building your application through conversation.

# Start interactive conversational builder (most common use case)
objectql ai

# Specify output directory
objectql ai ./src/my-app

The interactive mode:

  • Guides you step-by-step through application creation
  • Lets you describe what you want in natural language
  • Generates metadata, TypeScript implementations, and tests
  • Allows iterative refinement through dialogue
  • Provides suggestions for next steps

One-Shot Generation

For quick, non-interactive generation from a single description.

# Generate from a description
objectql ai generate -d "A task management system with projects and tasks"

# Generate complete enterprise application
objectql ai generate -d "CRM with customers, contacts, opportunities" -t complete -o ./src

# Generation types: basic, complete, custom (default)
objectql ai generate -d "Inventory system" -t complete

Options:

  • -d, --description <text> - Application description (required)
  • -o, --output <path> - Output directory [default: "./src"]
  • -t, --type <type> - Generation type: basic, complete, or custom [default: "custom"]

Generates:

  • ObjectQL metadata (objects, forms, views, pages, menus, etc.)
  • TypeScript implementations for actions and hooks
  • Jest test files for business logic validation

Validation

Validate metadata files using AI for compliance and best practices.

# Validate all metadata files
objectql ai validate ./src

# Validate with detailed output
objectql ai validate ./src -v

# Validate and auto-fix issues
objectql ai validate ./src --fix

Options:

  • <path> - Path to metadata directory (required)
  • --fix - Automatically fix issues where possible
  • -v, --verbose - Show detailed validation output

Checks:

  • YAML syntax validation
  • ObjectQL specification compliance
  • Business logic consistency
  • Data model best practices
  • Security and performance analysis
  • Falls back to basic validation if no API key is set

Chat Assistant

Interactive AI assistant for ObjectQL questions and guidance.

# Start chat assistant
objectql ai chat

# Start with an initial question
objectql ai chat -p "How do I create a lookup relationship?"

Options:

  • -p, --prompt <text> - Initial prompt for the AI

Complete Example Workflow

# Set your API key
export OPENAI_API_KEY=sk-your-api-key-here

# Option 1: Interactive (recommended) - Just type this!
objectql ai

# Option 2: Quick one-shot generation
objectql ai generate -d "Project management with tasks and milestones" -t complete

# Validate the generated files
objectql ai validate ./src -v

# Get help with questions
objectql ai chat -p "How do I add email notifications?"

Prerequisites

For AI-powered features, set your OpenAI API key:

export OPENAI_API_KEY=sk-your-api-key-here

Without an API key, basic validation (YAML syntax) is still available.

Project Initialization

init

Create a new ObjectQL project from a template.

# Interactive mode (prompts for options)
objectql init

# With options
objectql init --template basic --name my-project

# Available templates: basic, express-api, enterprise
objectql init -t express-api -n my-api-server

# Skip automatic dependency installation
objectql init --skip-install

# Skip git initialization
objectql init --skip-git

Options:

  • -t, --template <template> - Template to use (basic, express-api, enterprise) [default: "basic"]
  • -n, --name <name> - Project name
  • -d, --dir <path> - Target directory
  • --skip-install - Skip dependency installation
  • --skip-git - Skip git initialization

Templates:

  • basic - Minimal setup with basic examples
  • express-api - Express.js server with REST API
  • enterprise - Full-featured enterprise application structure

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/objectql.config.ts

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

Options:

  • -c, --config <path> - Path to objectql.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/objectql.config.ts

Options:

  • -c, --config <path> - Path to objectql.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/objectql.config.ts

Options:

  • -c, --config <path> - Path to objectql.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 (alias: d)

Start development server with hot reload support. This is the recommended command for local development.

# Start development server (port 3000)
objectql dev

# Specify options
objectql dev --dir ./src --port 8080

# Disable file watching
objectql dev --no-watch

The development server provides:

  • Swagger UI: http://localhost:<port>/swagger - Interactive API documentation
  • API Endpoint: http://localhost:<port>/ - Main API endpoint
  • OpenAPI Spec: http://localhost:<port>/openapi.json - Machine-readable API spec

Options:

  • -p, --port <number> - Port to listen on [default: "3000"]
  • -d, --dir <path> - Directory containing schema [default: "."]
  • --no-watch - Disable file watching (future feature)

start

Start production server. Loads configuration from objectql.config.ts/js if available.

# Start production server
objectql start

# Specify options
objectql start --port 8080 --dir ./dist

# Use custom config file
objectql start --config ./config/production.config.ts

Options:

  • -p, --port <number> - Port to listen on [default: "3000"]
  • -d, --dir <path> - Directory containing schema [default: "."]
  • -c, --config <path> - Path to objectql.config.ts/js

Environment Variables:

  • DATABASE_FILE - Path to SQLite database file (default: "./objectql.db")

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 (alias: s)

Note: This is an alias for the dev command, kept for backwards compatibility. Use objectql dev for new projects.

Start a lightweight development server with an in-memory database. Perfect for rapid prototyping without setting up a backend project.

# Start server in current directory (port 3000)
objectql serve

# Specify options
objectql serve --dir ./src/schema --port 8080

The server exposes:

  • Web Console (Swagger UI): http://localhost:<port>/swagger (GET) - Interactive API explorer
  • JSON API Endpoint: http://localhost:<port>/ (POST)
  • OpenAPI Spec: http://localhost:<port>/openapi.json (GET)

Options:

  • -p, --port <number> - Port to listen on [default: "3000"]
  • -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 ./objectql.config.ts

Options:

  • -c, --config <path> - Path to objectql.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' })

studio (alias: ui)

Start the ObjectQL Studio - a web-based admin interface.

# Start studio
objectql studio

# Custom port and directory
objectql studio --port 8080 --dir ./src

# Don't open browser automatically
objectql studio --no-open

Options:

  • -p, --port <number> - Port to listen on [default: "3000"]
  • -d, --dir <path> - Directory containing schema [default: "."]
  • --no-open - Do not open browser automatically

Typical Workflows

Starting a New Project

# 1. Create project from template
objectql init -t basic -n my-app

# 2. Navigate to project
cd my-app

# 3. Install dependencies (if skipped)
pnpm install

# 4. Start development
objectql studio

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 objectql.config.ts or objectql.config.js file in your project root:

// objectql.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_PORT - Default port for serve/studio commands
  • OBJECTQL_DB_URL - Database connection string

Getting Help

# Show all commands
objectql --help

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

License

MIT