Esmeralda CLI

CLI for Jade ORM

EN

About

Esmeralda is the official CLI for Jade ORM. It manages projects, migrations, schemas, seeds, and database operations in a simple and intuitive way.

Installation

npm install -g @alehandrosv/esmeralda-cli

Commands

init

Creates the basic structure of a Jade project. Supports interactive mode and --yes flag.

esmeralda init -n my-app          # Non-interactive
esmeralda init                     # Interactive (asks for config)
esmeralda init --yes               # Use defaults for everything

Generates:

my-app/
├── jade.config.lua
├── schema/
│   └── init.lua
├── migrations/
├── seeds/
└── lib/
    └── app.lua

generate

Generates a migration from schema changes.

esmeralda generate -n create_users
esmeralda generate --preview  # Preview SQL only

migrate

Runs all pending migrations.

esmeralda migrate
esmeralda migrate --preview  # Preview only

migrate status

Shows the status of all migrations (applied vs pending).

esmeralda migrate status

Output:

Migration Status:

  ✓ 20260715_create_users.lua
  ✓ 20260716_create_posts.lua
  ○ 20260717_add_email_index.lua (pending)

Applied: 2, Pending: 1

migrate create

Creates an empty migration.

esmeralda migrate create add_email_to_users

migrate rollback

Rolls back migrations.

esmeralda migrate rollback              # Rollback last
esmeralda migrate rollback --steps 3    # Rollback last 3

db pull

Introspects the database and generates entity files.

esmeralda db pull                # All tables
esmeralda db pull -t users       # Specific table

The generated files include:

• Column types and modifiers
• Primary key detection
• Foreign key relations (as comments)

db push

Pushes schema directly to database (without migrations).

esmeralda db push --force

This will:

• Create tables with CREATE TABLE IF NOT EXISTS
• Add foreign key constraints

db diff

Compares schema definitions with the current database state.

esmeralda db diff

Shows differences between your schema files and the live database.

db seed

Runs seed files from the seeds directory.

esmeralda db seed                   # All seeds
esmeralda db seed user              # Specific seed

schema-generate

Generates Lua entity files from declarative schema definitions.

esmeralda schema-generate

Reads declarative schema files and outputs Jade.Entity() Lua format.

Error Handling

All commands provide clear error messages with suggestions:

[error] Not a Jade project. Run 'esmeralda init' first.
[info] Suggestion: Run 'esmeralda init' in your project directory

[error] Failed to apply migration: 20260716_create_users.lua
[info] Check the migration file for syntax errors. Original error: attempt to call nil value

Enable debug mode for stack traces:

DEBUG=true esmeralda migrate

Docker Support

Esmeralda automatically detects docker-compose.yml and runs commands inside the container:

# With docker-compose.yml in project root
esmeralda migrate        # Runs inside container
esmeralda db seed        # Runs inside container

# Without docker-compose.yml
esmeralda migrate        # Runs locally (requires Lua/LuaJIT)

License

MIT

PT-BR

Sobre

Esmeralda e a CLI oficial do Jade ORM. Gerencia projetos, migrations, schemas, seeds e operacoes de banco de forma simples e intuitiva.

Instalacao

npm install -g @alehandrosv/esmeralda-cli

Comandos

init

Cria a estrutura basica de um projeto Jade. Suporta modo interativo e flag --yes.

esmeralda init -n my-app          # Nao-interativo
esmeralda init                     # Interativo (pergunta a config)
esmeralda init --yes               # Usar padroes para tudo

Gera:

my-app/
├── jade.config.lua
├── schema/
│   └── init.lua
├── migrations/
├── seeds/
└── lib/
    └── app.lua

generate

Gera uma migration a partir das alteracoes no schema.

esmeralda generate -n create_users
esmeralda generate --preview  # Apenas mostra o SQL

migrate

Roda todas as migrations pendentes.

esmeralda migrate
esmeralda migrate --preview  # Apenas mostra o que seria executado

migrate status

Mostra o status de todas as migrations (aplicadas vs pendentes).

esmeralda migrate status

Saida:

Migration Status:

  ✓ 20260715_create_users.lua
  ✓ 20260716_create_posts.lua
  ○ 20260717_add_email_index.lua (pending)

Applied: 2, Pending: 1

migrate create

Cria uma migration vazia.

esmeralda migrate create add_email_to_users

migrate rollback

Desfaz migrations.

esmeralda migrate rollback              # Desfaz ultima
esmeralda migrate rollback --steps 3    # Desfaz ultimas 3

db pull

Introspeciona o banco de dados e gera arquivos de entidade.

esmeralda db pull                # Todas as tabelas
esmeralda db pull -t users       # Tabela especifica

Os arquivos gerados incluem:

• Tipos de coluna e modificadores
• Deteccao de primary key
• Relacoes de foreign key (como comentarios)

db push

Empurra o schema diretamente para o banco (sem migrations).

esmeralda db push --force

Isso ira:

• Criar tabelas com CREATE TABLE IF NOT EXISTS
• Adicionar constraints de foreign key

db diff

Compara definicoes de schema com o estado atual do banco.

esmeralda db diff

Mostra diferencas entre seus arquivos de schema e o banco ao vivo.

db seed

Roda arquivos de seed do diretorio seeds.

esmeralda db seed                   # Todos os seeds
esmeralda db seed user              # Seed especifico

schema-generate

Gera arquivos Lua de entidade a partir de definicoes de schema declarativo.

esmeralda schema-generate

Le arquivos de schema declarativo e saida no formato Jade.Entity() Lua.

Tratamento de Erros

Todos os comandos fornecem mensagens de erro claras com sugestoes:

[error] Not a Jade project. Run 'esmeralda init' first.
[info] Suggestion: Run 'esmeralda init' in your project directory

Ative o modo debug para stack traces:

DEBUG=true esmeralda migrate

Suporte a Docker

O Esmeralda detecta automaticamente o docker-compose.yml e roda os comandos dentro do container:

# Com docker-compose.yml na raiz do projeto
esmeralda migrate        # Roda dentro do container
esmeralda db seed        # Roda dentro do container

# Sem docker-compose.yml
esmeralda migrate        # Roda localmente (requer Lua/LuaJIT)

Licenca

MIT