@famgia/omnify-cli

CLI tool for the Omnify schema system. Generate Laravel migrations and TypeScript types from YAML schemas.

Installation

# Global installation
npm install -g @famgia/omnify-cli

# Or use with npx
npx @famgia/omnify-cli <command>

# Or install in project
npm install @famgia/omnify-cli @famgia/omnify-laravel

Quick Start

# 1. Initialize project
npx omnify init

# 2. Edit omnify.config.ts to set your database URL

# 3. Define schemas in schemas/ directory

# 4. Validate and generate
npx omnify validate
npx omnify generate

Commands

omnify init

Initialize a new Omnify project.

omnify init [options]

Options:
  -f, --force    Overwrite existing files

Creates:

• omnify.config.ts - Configuration file with plugin setup
• schemas/User.yaml - Example schema file

After initialization, you'll see step-by-step setup instructions.

omnify validate

Validate all schema files for errors.

omnify validate [options]

Options:
  -v, --verbose  Show detailed output

Example output:

Validating Schemas

Loading schemas from ./schemas
Found 3 schema(s)
Validating schemas...

All schemas are valid!

omnify diff

Show pending schema changes without generating files.

omnify diff [options]

Options:
  -v, --verbose  Show detailed output

Uses Atlas to compare your schemas against the lock file and shows what migrations would be generated.

omnify generate

Generate Laravel migrations and TypeScript types.

omnify generate [options]

Options:
  -v, --verbose         Show detailed output
  --migrations-only     Only generate Laravel migrations
  --types-only          Only generate TypeScript types
  -f, --force           Generate even if no changes detected

Example:

# Generate everything
omnify generate

# Only migrations
omnify generate --migrations-only

# Only TypeScript types
omnify generate --types-only

# Force regeneration
omnify generate --force

# Verbose output
omnify generate -v

Configuration

Basic Configuration

Create omnify.config.ts:

import { defineConfig } from '@famgia/omnify';
import laravel from '@famgia/omnify-laravel/plugin';

export default defineConfig({
  schemasDir: './schemas',
  lockFilePath: './omnify.lock',

  database: {
    driver: 'mysql',
    devUrl: 'mysql://root:password@localhost:3306/omnify_dev',
  },

  plugins: [
    laravel({
      migrationsPath: 'database/migrations',
      typesPath: 'resources/js/types',
      singleFile: true,
    }),
  ],
});

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | schemasDir | string | Yes | Directory containing schema files | | lockFilePath | string | Yes | Path to lock file for change tracking | | database.driver | string | Yes | Database driver: mysql, postgres, sqlite | | database.devUrl | string | Yes* | Development database URL for Atlas (*required for generate) | | plugins | Plugin[] | No | Array of generator plugins |

Database URL Format

mysql://user:password@host:port/database
postgres://user:password@host:port/database
sqlite://path/to/file.db

Multiple Plugins

import { defineConfig } from '@famgia/omnify';
import laravel from '@famgia/omnify-laravel/plugin';
// Future plugins
// import prisma from '@famgia/omnify-prisma/plugin';
// import drizzle from '@famgia/omnify-drizzle/plugin';

export default defineConfig({
  schemasDir: './schemas',
  lockFilePath: './omnify.lock',

  database: {
    driver: 'mysql',
    devUrl: 'mysql://root@localhost:3306/dev',
  },

  plugins: [
    // Laravel migrations + TypeScript types
    laravel({
      migrationsPath: 'database/migrations',
      typesPath: 'resources/js/types',
    }),

    // Prisma schema (future)
    // prisma({
    //   schemaPath: 'prisma/schema.prisma',
    // }),
  ],
});

Schema Files

Basic Schema

schemas/User.yaml:

name: User
kind: object

properties:
  email:
    type: Email
    unique: true
  name:
    type: String
  age:
    type: Int
    nullable: true

options:
  timestamps: true
  softDeletes: true

With Associations

schemas/Post.yaml:

name: Post
kind: object

properties:
  title:
    type: String
  content:
    type: Text
  published:
    type: Boolean
    default: false

associations:
  author:
    type: belongsTo
    model: User
    foreignKey: user_id

options:
  timestamps: true

Enum

schemas/Status.yaml:

name: Status
kind: enum

values:
  - draft
  - published
  - archived

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Validation error |

Environment Variables

| Variable | Description | |----------|-------------| | OMNIFY_DEV_URL | Override database.devUrl from config | | DEBUG | Set to omnify:* for debug output |

Troubleshooting

"devUrl is required for generate command"

Set your database URL in omnify.config.ts:

database: {
  driver: 'mysql',
  devUrl: 'mysql://root:password@localhost:3306/dev_db',
},

"No schema files found"

Make sure your schemasDir points to the correct directory and contains .yaml or .json files.

"Atlas command not found"

Install Atlas CLI:

# macOS
brew install ariga/tap/atlas

# Linux
curl -sSf https://atlasgo.sh | sh

Related Packages

• @famgia/omnify - Main package
• @famgia/omnify-core - Core engine
• @famgia/omnify-types - Type definitions
• @famgia/omnify-laravel - Laravel generator
• @famgia/omnify-atlas - Atlas adapter

License

MIT