ormed_cli #

Command-line interface for the ormed ORM. Provides migration management, schema operations, seeding, and project scaffolding—similar to Laravel's Artisan CLI.

Installation #

dev_dependencies:
  ormed_cli: ^0.1.0

The CLI is available as the orm executable:

dart run ormed_cli:orm <command>

Commands #

For a complete walkthrough of setting up a project with the CLI, see the Getting Started Guide.

Project Initialization #

# Scaffold orm.yaml, migration registry, and directories
dart run ormed_cli:orm init

# Overwrite existing files
dart run ormed_cli:orm init --force

# Scan and register existing migrations/seeders
dart run ormed_cli:orm init --populate-existing

Migration Management #

# Create a new migration
dart run ormed_cli:orm make --name create_users_table
dart run ormed_cli:orm make --name create_posts_table --create --table posts
dart run ormed_cli:orm make --name add_column --format sql  # SQL format instead of Dart

# Run pending migrations
dart run ormed_cli:orm migrate
dart run ormed_cli:orm migrate --pretend      # Preview SQL without executing
dart run ormed_cli:orm migrate --step         # Apply one migration at a time
dart run ormed_cli:orm migrate --seed         # Run default seeder after
dart run ormed_cli:orm migrate --force        # Skip production confirmation

# Rollback migrations
dart run ormed_cli:orm migrate:rollback              # Rollback 1 migration
dart run ormed_cli:orm migrate:rollback --steps 3    # Rollback 3 migrations
dart run ormed_cli:orm migrate:rollback --batch 2    # Rollback specific batch
dart run ormed_cli:orm migrate:rollback --pretend    # Preview rollback SQL

# Reset/Refresh
dart run ormed_cli:orm migrate:reset      # Rollback ALL migrations
dart run ormed_cli:orm migrate:refresh    # Reset + re-migrate
dart run ormed_cli:orm migrate:fresh      # Drop all tables + re-migrate
dart run ormed_cli:orm migrate:fresh --seed

# Migration status
dart run ormed_cli:orm migrate:status
dart run ormed_cli:orm migrate:status --pending  # Only show pending

# Export SQL files
dart run ormed_cli:orm migrate:export        # Export pending migrations
dart run ormed_cli:orm migrate:export --all  # Export all migrations

Database Operations #

# Run seeders
dart run ormed_cli:orm seed
dart run ormed_cli:orm seed --class UserSeeder  # Specific seeder
dart run ormed_cli:orm seed --pretend           # Preview SQL

# Wipe database
dart run ormed_cli:orm db:wipe --force
dart run ormed_cli:orm db:wipe --drop-views

# Schema operations
dart run ormed_cli:orm schema:dump
dart run ormed_cli:orm schema:dump --prune  # Delete migration files after dump
dart run ormed_cli:orm schema:describe
dart run ormed_cli:orm schema:describe --json

Multi-Database Support #

# Target specific connection
dart run ormed_cli:orm migrate --connection analytics
dart run ormed_cli:orm seed --connection analytics
dart run ormed_cli:orm migrate:status --connection analytics

Configuration (orm.yaml) #

The init command scaffolds this configuration file:

driver:
  type: sqlite                              # sqlite, mysql, postgres
  options:
    database: database.sqlite               # Connection-specific options

migrations:
  directory: lib/src/database/migrations    # Migration files location
  registry: lib/src/database/migrations.dart # Migration registry file
  ledger_table: orm_migrations              # Table tracking applied migrations
  schema_dump: database/schema.sql          # Schema dump output
  format: dart                              # Migration format: dart or sql

seeds:
  directory: lib/src/database/seeders
  registry: lib/src/database/seeders.dart

Multi-Connection Configuration #

connections:
  default:
    type: sqlite
    options:
      database: main.sqlite
  analytics:
    type: postgres
    options:
      host: localhost
      port: 5432
      database: analytics
      username: user
      password: secret

default_connection: default

Directory Structure #

After running init:

project/
├── orm.yaml
├── database/
│   └── schema.sql
└── lib/src/database/
    ├── migrations/
    │   └── m_YYYYMMDDHHMMSS_migration_name.dart
    ├── migrations.dart   (registry)
    ├── seeders/
    │   └── database_seeder.dart
    └── seeders.dart      (registry)

Migration Formats #

Ormed supports both Dart and SQL migrations in the same project. The CLI automatically registers them in your migration registry.

Dart Migrations (default) #

Type-safe migrations using a fluent SchemaBuilder.

dart run ormed_cli:orm make --name create_users_table

class CreateUsersTable extends Migration {
  @override
  void up(SchemaBuilder schema) {
    schema.create('users', (table) {
      table.id();
      table.string('email').unique();
      table.timestamps();
    });
  }

  @override
  void down(SchemaBuilder schema) {
    schema.drop('users');
  }
}

SQL Migrations #

Raw .sql files for complex schema changes.

dart run ormed_cli:orm make --name add_bio_to_users --format sql

This creates a directory:

m_20251220120000_add_bio_to_users/
├── up.sql
└── down.sql

Simultaneous Support #

The CLI runner is format-agnostic. It builds a unified timeline of all registered migrations based on their timestamps. When you run migrate, it will execute Dart classes and SQL files in the correct chronological order. This allows you to use Dart for standard schema changes and drop down to SQL for complex, database-specific logic without breaking the migration flow.

Runtime Bootstrapping #

When using the CLI, you should use the generated bootstrapOrm() function to initialize your ModelRegistry. This ensures all models, factories, and metadata are correctly registered.

import 'package:ormed/ormed.dart';
import 'orm_registry.g.dart';

void main() {
  final registry = bootstrapOrm();
  // ...
}

Global Options #

Most commands support these flags:

Creating Seeders #

dart run ormed_cli:orm make --name UserSeeder --seeder

class UserSeeder extends DatabaseSeeder {
  @override
  Future<void> run() async {
    await seed<User>([
      {'email': 'admin@example.com', 'name': 'Admin'},
      {'email': 'user@example.com', 'name': 'User'},
    ]);
  }
}