CLI Guide

The ObjectQL CLI (@objectql/cli) focuses on metadata scaffolding, type generation, database workflows, and local tooling. Runtime lifecycle commands are delegated to @objectstack/cli.

1. Installation

The CLI is typically installed as a dev dependency in your project.

npm install -D @objectql/cli

You can then run it via npx objectql or add scripts to your package.json.

2. Core Commands

2.1 `create` (Create Project)

Project scaffolding is now provided by @objectstack/cli.

npx objectstack create
# or
npx os create

2.2 `generate` (Type Generation)

Scans your *.object.yml files and generates TypeScript interfaces. This is crucial for maintaining type safety in your Hooks and Actions. Alias: g

npx objectql generate [options]

Options:

Option	Alias	Default	Description
`--source <path>`	`-s`	`.`	Root directory to search for object files.
`--output <path>`	`-o`	`./src/generated`	Directory where `.ts` files will be generated.

Example:

# Generate types from /src/objects to /src/types
npx objectql generate --source ./src/objects --output ./src/types

2.3 `new` (Scaffold Metadata)

Generate a new metadata file (Object, View, Form, etc.) in the project.

npx objectql new <type> <name> [options]

Arguments:

<type>: The type of metadata to generate (e.g., object, view, page).
<name>: The name of the file/entity.

Options:

Option	Alias	Default	Description
`--dir <path>`	`-d`	`.`	Output directory.

Example:

npx objectql new object customer

3. Development Tools

3.1 `dev` (Development Server)

Development server is now provided by @objectstack/cli:

npx objectstack dev
# or
npx os dev

3.2 `serve` (Production Server)

Production server is now provided by @objectstack/cli:

npx objectstack serve
# or
npx os serve

3.3 `repl` (Interactive Shell)

Starts an interactive terminal similar to the MongoDB shell, allowing you to directly query your database using the ObjectQL API. Alias: r

npx objectql repl [options]

Options:

Option	Alias	Default	Description
`--config <path>`	`-c`	-	Path to `objectstack.config.ts/js`.

Example Session:

objectql> await tasks.find({ status: 'todo' })
[ { id: 1, title: 'Fix bug', status: 'todo' } ]

4. Internationalization (i18n)

Tools for managing translations.

4.1 `i18n extract`

Extract translatable strings from metadata files into JSON.

npx objectql i18n extract [options]

Options:

Option	Alias	Default	Description
`--source <path>`	`-s`	`.`	Source directory to scan.
`--output <path>`	`-o`	`./src/i18n`	Output directory for translation files.
`--lang <lang>`	`-l`	`en`	Language code.

4.2 `i18n init`

Initialize i18n structure for a new language.

npx objectql i18n init <lang> [options]

Options:

Option	Alias	Default	Description
`--base-dir <path>`	`-b`	`./src/i18n`	Base i18n directory.

4.3 `i18n validate`

Validate translation completeness against a base language.

npx objectql i18n validate <lang> [options]

Options:

Option	Alias	Default	Description
`--base-dir <path>`	`-b`	`./src/i18n`	Base i18n directory.
`--base-lang <lang>`		`en`	Base language to compare against.

5. Database Migration

Manage database schema changes.

5.1 `migrate`

Run pending database migrations.

npx objectql migrate [options]

Options:

Option	Alias	Default	Description
`--config <path>`	`-c`	-	Path to `objectstack.config.ts/js`.
`--dir <path>`	`-d`	`./migrations`	Migrations directory.

5.2 `migrate create`

Create a new migration file.

npx objectql migrate create <name> [options]

Options:

Option	Alias	Default	Description
`--dir <path>`	`-d`	`./migrations`	Migrations directory.

5.3 `migrate status`

Show the status of migrations (applied/pending).

npx objectql migrate status [options]

Options:

Option	Alias	Default	Description
`--config <path>`	`-c`	-	Path to `objectstack.config.ts/js`.
`--dir <path>`	`-d`	`./migrations`	Migrations directory.

6. Integration with Workflow

We recommend adding the CLI commands to your lifecycle scripts.

package.json:

{
  "scripts": {
    "codegen": "objectql generate -s ./src -o ./src/generated",
    "build": "npm run codegen && tsc",
    "dev": "npx objectstack dev",
    "serve": "npx objectstack serve"
  }
}

This ensures that whenever you build or start your app, your TypeScript types are perfectly synced with your YAML definitions.

CLI Guide

On this page