@eloquentjs/cli

The official CLI for EloquentJS — scaffold, migrate, seed, and manage your project from the terminal.

Installation

# Install globally
npm install -g @eloquentjs/cli

# Or use via npx
npx @eloquentjs/cli <command>

# Or within a monorepo / local project
npm install --save-dev @eloquentjs/cli

After global install, the eloquent (or ejs) command is available everywhere.

Quick Start

# Initialize EloquentJS in your project
eloquent init

# Initialize with MongoDB instead of PostgreSQL
eloquent init --driver=mongodb

# Create a model
eloquent make:model User

# Create a model + migration + factory + seeder all at once
eloquent make:model Post --all

# Run migrations
eloquent migrate

# Seed the database
eloquent db:seed

All Commands

Project Setup

| Command | Description | |---|---| | eloquent init | Scaffold eloquent.config.js, directory structure, and .env.example | | eloquent init --driver=mongodb | Initialize with MongoDB driver | | eloquent list | List all available commands |

Generators (make:*)

| Command | Description | |---|---| | eloquent make:model <Name> | Generate a model class | | eloquent make:model <Name> --migration | Model + migration | | eloquent make:model <Name> --factory | Model + factory | | eloquent make:model <Name> --seed | Model + seeder | | eloquent make:model <Name> --all | Model + migration + factory + seeder | | eloquent make:model <Name> --soft-deletes | Add softDeletes = true | | eloquent make:migration <name> | Generate a migration file | | eloquent make:seeder <Name> | Generate a seeder class | | eloquent make:factory <Name> | Generate a factory class |

Smart migration templates — the CLI detects your intent from the name:

eloquent make:migration create_users_table       # → CREATE TABLE template
eloquent make:migration add_avatar_to_users      # → ALTER TABLE ADD COLUMN template
eloquent make:migration drop_bio_from_profiles   # → ALTER TABLE DROP COLUMN template
eloquent make:migration rename_posts_to_articles # → RENAME TABLE template
eloquent make:migration drop_old_logs_table      # → DROP TABLE template

Migrations

| Command | Description | |---|---| | eloquent migrate | Run all pending migrations | | eloquent migrate:rollback | Rollback the last batch | | eloquent migrate:rollback --step=3 | Rollback the last 3 batches | | eloquent migrate:reset | Rollback ALL migrations | | eloquent migrate:refresh | Reset + re-run all migrations | | eloquent migrate:refresh --seed | Refresh then seed | | eloquent migrate:fresh | Drop all tables + re-run migrations | | eloquent migrate:fresh --seed | Fresh + seed | | eloquent migrate:status | Show which migrations have run |

Database

| Command | Description | |---|---| | eloquent db:seed | Run DatabaseSeeder | | eloquent db:seed --class=UserSeeder | Run a specific seeder | | eloquent db:wipe --force | Drop all tables (requires --force) |

Generate (from live models)

These commands load your actual model files, introspect them via @eloquentjs/codegen, and write output files. Requires @eloquentjs/codegen to be installed.

npm install @eloquentjs/codegen

| Command | Output | Description | |---|---|---| | eloquent generate:graphql | schema.graphql | Full GraphQL SDL from all models | | eloquent generate:types | src/types/models.d.ts | TypeScript interfaces for all models | | eloquent generate:openapi | openapi.json | OpenAPI 3.0 spec mirroring your REST routes |

Options shared by all generate:* commands:

| Flag | Description | |---|---| | --models=User,Post | Generate for specific models only | | --models-dir=<path> | Override the models directory (default: from eloquent.config.js) | | --out=<file> | Custom output file path |

generate:graphql options:

eloquent generate:graphql                           # all models → schema.graphql
eloquent generate:graphql --out=src/schema.graphql  # custom output path
eloquent generate:graphql --pagination=relay         # use Relay cursor pagination
eloquent generate:graphql --no-subscriptions         # exclude Subscription type
eloquent generate:graphql --models=User,Post         # specific models only

generate:types options:

eloquent generate:types                             # all models → src/types/models.d.ts
eloquent generate:types --out=types/index.d.ts      # custom path

Generated file includes PaginationMeta, PaginatedResult<T>, and an interface + CreateInput + UpdateInput for every model.

generate:openapi options:

eloquent generate:openapi                           # → openapi.json
eloquent generate:openapi --format=yaml             # → openapi.yaml
eloquent generate:openapi --out=docs/openapi.json   # custom path
eloquent generate:openapi --title="My API"          # custom title

Generated spec mirrors all routes from @eloquentjs/api including pagination query params, soft-delete routes, and error response schemas. View it with:

npx @redocly/cli preview-docs openapi.json
# or
npx swagger-ui-cli openapi.json

Global Flags

| Flag | Description | |---|---| | --force / -f | Overwrite existing files, skip confirmations | | --verbose / -v | Print full error stack traces |

Configuration (eloquent.config.js)

Generated by eloquent init. Customize paths and connection:

export default {
  connection: {
    driver:   'pgsql',
    host:     process.env.DB_HOST     ?? 'localhost',
    port:     Number(process.env.DB_PORT ?? 5432),
    database: process.env.DB_DATABASE ?? 'myapp',
    user:     process.env.DB_USERNAME ?? 'postgres',
    password: process.env.DB_PASSWORD ?? '',
  },

  paths: {
    models:     'app/models',        // where models are generated
    migrations: 'database/migrations',
    seeders:    'database/seeders',
    factories:  'database/factories',
  },
}

Generated File Examples

Model (eloquent make:model Post --all)

// app/models/Post.js
import { Model } from '@eloquentjs/core'

export default class Post extends Model {
  static table    = 'posts'
  static fillable = []
  static hidden   = []

  static casts = {
    // created_at: 'date',
    // is_active:  'boolean',
  }

  // posts()   { return this.hasMany(Comment) }
  // static scopePublished(qb) { return qb.where('status', 'published') }
  // static async creating(record) { }
}

Migration (eloquent make:migration create_posts_table)

// database/migrations/20240315120000_create_posts_table.js
import { Migration, Schema } from '@eloquentjs/core'

export default class CreatePostsTable extends Migration {
  async up() {
    await Schema.create('posts', t => {
      t.id()
      // t.string('title')
      // t.text('body').nullable()
      t.timestamps()
    })
  }

  async down() {
    await Schema.dropIfExists('posts')
  }
}

Seeder

// database/seeders/PostSeeder.js
import { Seeder } from '@eloquentjs/core'

export default class PostSeeder extends Seeder {
  async run() {
    // await PostFactory.new().count(10).create()
    console.log('PostSeeder done.')
  }
}

Factory

// database/factories/PostFactory.js
import { Factory } from '@eloquentjs/core'
import { faker } from '@faker-js/faker'
import Post from '../models/Post.js'

export default class PostFactory extends Factory {
  model = Post

  definition() {
    return {
      // title: faker.lorem.sentence(),
      // body:  faker.lorem.paragraphs(3),
    }
  }

  // published() { return this.state({ status: 'published' }) }
}

Migration Tracking

Migrations are tracked in a _migrations table created automatically in your database:

_migrations
  id          SERIAL PRIMARY KEY
  migration   VARCHAR(255) UNIQUE   ← filename e.g. 20240315_create_users_table.js
  batch       INTEGER               ← group number for rollbacks
  ran_at      TIMESTAMPTZ

Rollbacks undo the last batch by default. Use --step=N to roll back multiple batches.

Workflow Example

# 1. New project
mkdir myapp && cd myapp
npm init -y
npm install @eloquentjs/core @eloquentjs/pgsql @eloquentjs/cli
eloquent init

# 2. Create models
eloquent make:model User --all
eloquent make:model Post --migration --factory

# 3. Edit migrations, then run
eloquent migrate
eloquent migrate:status

# 4. Seed data
eloquent db:seed --class=UserSeeder

# 5. During development — wipe and start fresh
eloquent migrate:fresh --seed

AI Agent Integration

MCP Server (@eloquentjs/mcp)

If you use AI coding tools that support MCP (Claude.ai Desktop, Cursor, Windsurf), install the MCP server for the best experience. The agent gets 21 tools to introspect your models, generate code, run migrations, and look up documentation — without reading your files manually.

npm install -g @eloquentjs/mcp

# Claude Desktop (~/.claude/mcp_config.json)
# { "mcpServers": { "eloquentjs": { "command": "npx", "args": ["@eloquentjs/mcp", "--cwd", "/path/to/project"] } } }

eloquent-mcp --cwd .    # start the server

See @eloquentjs/mcp for full setup instructions.

Agent Files (no MCP required)

For tools that don't use MCP, the agent-files/ directory in the monorepo root contains ready-to-use context files:

| File | Drop it here | |---|---| | CLAUDE.md | Project root (auto-loaded by Claude) | | .cursorrules | Project root | | .windsurfrules | Project root | | copilot-instructions.md | .github/copilot-instructions.md | | skills/db-skill.md | Any agent knowledge base |

License

MIT