Mocktail-CLI

Note: .env file was sanitized in this package release. Use .env.example to set DATABASE_URL before running anything that needs a DB.

Mocktail‑CLI — The comprehensive schema‑aware mock data generator for developers. Generate realistic, relation‑aware mock data from any schema type directly from the command line with enhanced relation detection, performance optimization, and extensible plugin system.

Table of contents

1. What is Mocktail‑CLI?
2. Key features
3. Enhanced features (v1.4+)
4. Why use Mocktail‑CLI?
5. Quickstart
6. CLI reference (examples)
7. Configuration
8. Example workflows
9. Plugin system
10. Performance optimization
11. Competitor comparison
12. Roadmap
13. Contributing
14. License & Contact

What is Mocktail‑CLI?

Mocktail-CLI is the most comprehensive schema-aware CLI tool for generating realistic mock data based on any schema type. It supports 15+ schema types including Prisma, GraphQL, JSON Schema, OpenAPI, TypeScript, Protocol Buffers, Avro, XML Schema, SQL DDL, Mongoose, Sequelize, Joi, Yup, Zod, and more with nested relations, circular relation handling, deterministic seeds, schema auto-detection, and multiple output formats. Perfect for building, testing, and prototyping without waiting on backend data.

Key features

• Comprehensive schema support — works with 15+ schema types including Prisma, GraphQL, JSON Schema, OpenAPI, TypeScript, Protocol Buffers, Avro, XML Schema, SQL DDL, Mongoose, Sequelize, Joi, Yup, Zod, and more.
• Schema auto-detection — automatically finds and validates schema files.
• Advanced relation presets — generate realistic domain graphs (blog, ecommerce, social).
• Schema-aware generation — matches model types and relations across all schema types.
• Relation handling — supports deep and circular relations with controlled --depth.
• Deterministic seeds — reproducible datasets with --seed and --seed-value.
• Multiple output formats — JSON, SQL, CSV, TypeScript.
• Custom generators — define per-model faker rules in mocktail-cli.config.js.
• CLI-first — quick commands for generate, seed, and export.

Enhanced features (v1.4+)

🎯 NEW: Extensible Type System

• Custom scalar support — GraphQL custom scalars (EmailAddress, URL, JSON, DateTime, etc.)
• Format-based generation — JSON Schema formats (email, uri, date-time, uuid, etc.)
• Context-aware generation — Email addresses match user names, realistic relationships
• 50+ built-in generators — Email, phone, URL, UUID, dates, addresses, and more
• Plugin architecture — Easy to register custom type generators

🔄 NEW: Advanced Circular Dependency Resolution

• Smart cycle detection — Finds all circular dependencies in complex schemas
• Multiple resolution strategies — Smart-break, lazy-loading, partial-references
• Cycle classification — Self-reference, simple, and complex cycle types
• Strength analysis — Weak (optional) vs strong (required) relationship cycles
• Detailed reporting — Shows detected cycles and applied resolution strategies

🧠 Enhanced Relation Detection

• Multi-strategy detection — Direct references, foreign keys, naming conventions, schema annotations, and inference
• Confidence scoring — Each detected relation has a confidence score (0-1) with configurable thresholds
• Advanced patterns — Supports complex naming conventions like userId, user_id, userRef, posts, userList
• Schema annotations — Recognizes @relation, @belongsTo, @hasMany patterns

🚨 Better Error Messages

• Contextual information — Schema path, model names, field names, line numbers
• Actionable suggestions — Step-by-step solutions for common issues
• Documentation links — Direct links to relevant documentation
• Severity levels — Critical, high, medium, low severity indicators

⚡ Performance Optimization

• Memory monitoring — Real-time memory usage tracking with automatic pressure handling
• Intelligent batching — Automatic batch size calculation based on available memory
• Progress tracking — Real-time progress indicators with ETA and speed monitoring
• Timeout protection — Configurable timeout limits with automatic cleanup

🔌 Plugin System

• Extensible architecture — Custom generators, validators, and transformers
• Built-in plugins — Date generator, email generator, and custom validator plugins
• Plugin management — Load, enable, disable, and configure plugins
• Hook system — Execute code at various stages of generation

🌍 Internationalization & Localization (v1.4.2+)

• Locale support — Generate culturally appropriate data for different regions
• 20+ supported locales — English, Spanish, French, German, Japanese, Korean, Chinese, and more
• Locale-aware generation — Names, addresses, phone numbers, and emails match the specified locale
• Easy locale switching — Simple --locale flag to change data generation locale

🎨 UI/UX Improvements

• Enhanced output formatting — Color-coded messages and structured information
• Progress indicators — Real-time progress bars with batch tracking
• Better CLI experience — Improved help messages and verbose output options

Why use Mocktail‑CLI?

• Save development time — no more hand‑crafting mock data.
• Build realistic prototypes — frontend and backend can develop in parallel.
• Reliable testing — deterministic seeds make tests repeatable.
• Flexible outputs — works with files, databases, or API mocks.

Quickstart

Install

# global install
npm i -g mocktail-cli

# or run on demand
npx mocktail-cli generate --help

Generate mock data from any schema

# Prisma schema
npx mocktail-cli generate \
  --schema ./prisma/schema.prisma \
  --type prisma \
  --models User,Post \
  --count 50 \
  --out ./mocks/data.json \
  --format json \
  --seed

# GraphQL schema
npx mocktail-cli generate \
  --schema ./schema.graphql \
  --type graphql \
  --models User,Post \
  --count 50

# JSON Schema
npx mocktail-cli generate \
  --schema ./schema.json \
  --type json-schema \
  --count 50

# OpenAPI specification
npx mocktail-cli generate \
  --schema ./openapi.yaml \
  --type openapi \
  --count 50

# TypeScript interfaces
npx mocktail-cli generate \
  --schema ./types.ts \
  --type typescript \
  --count 50

# Protocol Buffers
npx mocktail-cli generate \
  --schema ./schema.proto \
  --type protobuf \
  --count 50

# Avro schema
npx mocktail-cli generate \
  --schema ./schema.avsc \
  --type avro \
  --count 50

# XML Schema
npx mocktail-cli generate \
  --schema ./schema.xsd \
  --type xml-schema \
  --count 50

# SQL DDL
npx mocktail-cli generate \
  --schema ./schema.sql \
  --type sql-ddl \
  --count 50

# Mongoose schemas
npx mocktail-cli generate \
  --schema ./models.js \
  --type mongoose \
  --count 50

# Sequelize models
npx mocktail-cli generate \
  --schema ./models.js \
  --type sequelize \
  --count 50

# Joi validation schemas
npx mocktail-cli generate \
  --schema ./validation.js \
  --type joi \
  --count 50

# Yup validation schemas
npx mocktail-cli generate \
  --schema ./validation.js \
  --type yup \
  --count 50

# Zod schemas
npx mocktail-cli generate \
  --schema ./validation.ts \
  --type zod \
  --count 50

• --depth 2 — set how deep nested relations go (depth > 1 enables relations).
• --relations — enable automatic relation generation (works with any depth).
• --out — output to a file or stdout.
• --preset blog — generate domain-specific data.

Supported Schema Types

Mocktail-CLI supports 15+ schema types out of the box:

| Schema Type | File Extensions | Description | Auto-Detection | |-------------|----------------|-------------|----------------| | Prisma | .prisma | Database schema definitions | ✅ | | GraphQL | .graphql, .gql | API schema definitions | ✅ | | JSON Schema | .json | Data validation schemas | ✅ | | OpenAPI | .yaml, .yml, .json | API specification schemas | ✅ | | TypeScript | .ts, .tsx | Interface and type definitions | ✅ | | Protocol Buffers | .proto | Google's data serialization format | ✅ | | Avro | .avsc, .avro | Apache Avro data serialization | ✅ | | XML Schema | .xsd | XML document structure definitions | ✅ | | SQL DDL | .sql | Database table definitions | ✅ | | Mongoose | .js | MongoDB object modeling | ✅ | | Sequelize | .js | SQL ORM model definitions | ✅ | | Joi | .js | Object schema validation | ✅ | | Yup | .js | Schema validation library | ✅ | | Zod | .ts, .js | TypeScript-first schema validation | ✅ |

Auto-Detection

Mocktail-CLI automatically detects schema types based on:

• File extensions (e.g., .prisma → Prisma, .graphql → GraphQL)
• File content patterns (e.g., model User → Prisma, type User → GraphQL)
• Import statements (e.g., import * as mongoose → Mongoose)

You can also explicitly specify the schema type using --type:

# Auto-detect schema type
mocktail-cli generate --schema ./my-schema

# Explicitly specify schema type
mocktail-cli generate --schema ./my-schema --type typescript

v1.4.0 New Features Examples

Custom Scalar Support (GraphQL)

# schema.graphql
scalar EmailAddress
scalar URL
scalar JSON
scalar DateTime

type User {
  id: UUID!
  email: EmailAddress!        # Generates: "[email protected]"
  website: URL               # Generates: "https://example.com"
  metadata: JSON             # Generates: { key: "data", value: "content" }
  createdAt: DateTime!       # Generates: "2024-01-15T10:30:00Z"
}

# Generate with custom scalars
mocktail-cli generate --schema schema.graphql --count 5

Format Support (JSON Schema)

{
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "website": { "type": "string", "format": "uri" },
    "birthDate": { "type": "string", "format": "date" },
    "lastLogin": { "type": "string", "format": "date-time" },
    "id": { "type": "string", "format": "uuid" }
  }
}

Circular Dependency Resolution

# Complex schema with cycles
mocktail-cli generate --schema complex-schema.graphql --count 3

# Output shows cycle detection:
# 🔄 Detected 3 circular dependencies:
#   • self-reference cycle: User → User (weak)
#   • complex-cycle cycle: User → Post → Comment → User (strong)
# 🛠️ Applied resolution strategy: smart-break
#   • Deferred 2 relations for later population

Locale Support (v1.4.2+)

# Generate Spanish mock data
mocktail-cli generate --locale es --count 5
# Output: Names like "María García", "José Luis Rodríguez"

# Generate French mock data
mocktail-cli generate --locale fr --count 5
# Output: Names like "Pierre Dubois", "Marie Lefebvre"

# Generate Japanese mock data
mocktail-cli generate --locale ja --count 5
# Output: Names like "田中太郎", "佐藤花子"

# Generate German mock data with relations
mocktail-cli generate --locale de --relations --count 10
# Output: Names like "Hans Müller", "Anna Schmidt"

Supported Locales

en (English), es (Spanish), fr (French), de (German), it (Italian), 
pt_BR (Portuguese Brazil), ja (Japanese), ko (Korean), zh_CN (Chinese Simplified), 
ru (Russian), ar (Arabic), hi (Hindi), nl (Dutch), sv (Swedish), 
da (Danish), no (Norwegian), fi (Finnish), pl (Polish), tr (Turkish), th (Thai)

CLI reference (examples)

Basic usage

# Generate 20 Users (flat records)
mocktail-cli generate --models User --count 20

# Generate Users and Posts with specific counts
mocktail-cli generate --models User,Post --count 10,30 --out ./mocks

# Generate SQL inserts instead of JSON
mocktail-cli generate --format sql --out ./seeds

# Use a preset for ecommerce data
mocktail-cli generate --preset ecommerce --count 100

# Generate locale-specific data
mocktail-cli generate --locale es --count 20 --out ./spanish-data
mocktail-cli generate --locale fr --relations --count 50

Understanding --depth and --relations flags

The --depth and --relations flags work independently to control relation generation:

# Flat records (no relations)
mocktail-cli generate --count 5
# or
mocktail-cli generate --depth 1 --count 5

# Nested relations with depth 2
mocktail-cli generate --depth 2 --count 5

# Enable relations with default depth (2)
mocktail-cli generate --relations --count 5

# Both flags work together
mocktail-cli generate --relations --depth 3 --count 5

# Disable relations even with depth > 1
mocktail-cli generate --depth 2 --no-nest --count 5

Key points:

• --depth 1 = Flat records (no nesting)
• --depth 2+ = Enables relations with specified nesting level
• --relations = Enables relations with default depth of 2
• --no-nest = Disables relations regardless of other flags

Full option list

Basic Options

| Option | Alias | Description | |--------|-------|-------------| | -c, --count <number> | | Number of records per model (default: 5) | | -o, --out <directory> | | Output directory | | -f, --format <type> | | Output format: json, sql, ts, csv (default: json) | | -s, --schema <path> | | Schema path (default: ./prisma/schema.prisma, auto-detect enabled) | | -t, --type <type> | | Schema type: prisma, graphql, json-schema, openapi (auto-detected if not specified) | | -m, --models <models> | | Comma-separated list of models (optional) | | --mock-config <path> | | Path to mocktail-cli.config.js | | -d, --depth <number> | | Nested relation depth - depth > 1 enables relations (default: 1) | | --no-nest | | Disable nested relations (flat structure) | | --relations | | Enable automatic relation generation (works with any depth) | | --dedupe | | Enable deduplication of records | | --pretty | | Pretty-print JSON output (default: true) | | --no-pretty | | Disable pretty-printing JSON output | | --no-log | | Suppress console logs during mock generation | | --seed | | Insert generated data into DB | | --seed-value <number> | | Seed value for reproducible data generation | | --locale <locale> | | Locale for generating culturally appropriate data (e.g., en, es, fr, ja) (default: en) | | --preset <type> | | Relation preset: blog, ecommerce, social | | --force-logo | | Force show the logo animation even if shown before | | -h, --help | | Display help with usage and examples |

Enhanced Options (v1.3+)

| Option | Description | |--------|-------------| | --enable-advanced-relations | Enable enhanced relation detection with confidence scoring | | --relation-confidence <threshold> | Set relation detection confidence threshold (0-1, default: 0.5) | | --performance-mode | Enable performance optimizations for large datasets | | --memory-limit <mb> | Set memory limit in MB (default: 1024) | | --batch-size <size> | Set batch size for processing (default: 1000) | | --enable-plugins | Enable plugin system | | --plugin-dir <path> | Directory to load plugins from | | --verbose | Enable verbose output with detailed information | | --quiet | Suppress output except errors | | --no-logo | Suppress logo output globally |

---

## Configuration

Define a `mocktail-cli.config.js` or `mocktail-cli.config.json` to customize generation.

```js
module.exports = {
  defaults: { locale: 'en', seedConsistency: true },
  models: {
    User: { count: 20, faker: { name: 'fullName', email: 'email' } },
    Post: { count: 50, relations: { author: { connectBy: 'User' } } }
  }
}

Plugin system

Built-in Plugins

Mocktail-CLI includes several built-in plugins for enhanced data generation:

Date Generator Plugin

# Automatically generates context-aware dates
mocktail-cli generate --enable-plugins --count 100

Email Generator Plugin

# Generates realistic email addresses with domain patterns
mocktail-cli generate --enable-plugins --count 100

Creating Custom Plugins

// plugins/my-generator.js
module.exports = {
  name: 'my-generator',
  version: '1.0.0',
  description: 'Custom data generator',
  
  generators: [
    {
      name: 'customField',
      fieldTypes: ['string'],
      generate: (field, context) => `custom-${Math.random()}`,
      validate: (field) => field.name === 'customField'
    }
  ],
  
  hooks: {
    beforeGeneration: async (context) => {
      console.log('🚀 Custom plugin activated!');
    }
  }
};

Using Plugins

# Load plugins from directory
mocktail-cli generate --enable-plugins --plugin-dir ./plugins

# Use with specific models
mocktail-cli generate --models User --enable-plugins --count 1000

Performance optimization

Large Dataset Generation

# Generate 100,000 records with performance optimizations
mocktail-cli generate \
  --count 100000 \
  --performance-mode \
  --memory-limit 4096 \
  --batch-size 2000 \
  --enable-advanced-relations

Memory-Optimized Generation

# Limited memory environment
mocktail-cli generate \
  --count 50000 \
  --performance-mode \
  --memory-limit 1024 \
  --batch-size 1000 \
  --format csv

Performance Configuration

// mocktail-cli.config.js
module.exports = {
  performance: {
    maxMemoryUsage: 2048, // MB
    batchSize: 1000,
    enableMemoryMonitoring: true,
    enableProgressTracking: true,
    timeoutMs: 300000 // 5 minutes
  }
};

Example workflows

Frontend prototyping

1. Generate realistic data with relations: mocktail-cli generate --relations --count 50
2. Feed the output to your mock API server.

Testing with consistent seeds

1. Generate with seed: mocktail-cli generate --relations --seed --seed-value 42
2. Run tests with consistent fixtures.

Deep nested data for complex UIs

1. Generate deeply nested data: mocktail-cli generate --depth 3 --count 20
2. Perfect for testing complex component hierarchies.

Domain-specific seeding

mocktail-cli generate --preset social --relations --count 100 --seed

Enhanced workflows (v1.3+)

Large dataset generation with performance optimization

# Generate 1 million records with all optimizations
mocktail-cli generate \
  --count 1000000 \
  --performance-mode \
  --memory-limit 8192 \
  --batch-size 5000 \
  --enable-advanced-relations \
  --format sql \
  --out ./large-dataset

Plugin-enhanced generation

# Use custom plugins for enhanced data generation
mocktail-cli generate \
  --enable-plugins \
  --plugin-dir ./custom-plugins \
  --enable-advanced-relations \
  --count 10000

Production-ready data generation

# Full production setup with all enhancements
mocktail-cli generate \
  --schema ./schema.prisma \
  --count 100000 \
  --enable-advanced-relations \
  --relation-confidence 0.8 \
  --performance-mode \
  --memory-limit 4096 \
  --batch-size 2000 \
  --enable-plugins \
  --format json \
  --out ./production-data \
  --seed \
  --seed-value 42

Competitor Comparison

How Mocktail-CLI compares with other schema-aware mock data tools:

| Feature / Tool | Mocktail-CLI | Prisma-Seed | Prisma-Generator-Fake | Mockoon / MirageJS | faker-js | |---------------------------------------------|-----------------|-------------|----------------------|------------------|----------| | Multi-schema support (Prisma, GraphQL, etc.)| ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No | | Schema aware (reads schema) | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | ❌ No | | Auto-detect schema files | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No | | Handles relations (deep / circular-safe) | ✅ Deep + safe | ⚠️ Limited | ⚠️ Limited | ❌ Manual | ❌ No | | Deterministic seeds | ✅ --seed-value| ⚠️ Partial | ⚠️ Partial | ❌ No | ✅* | | Output formats | ✅ JSON / SQL / CSV / TS | ❌ Mostly JSON | ❌ Mostly JSON | ✅ JSON / API | ⚠️ Code-driven only | | CLI-first workflow | ✅ Yes | ⚠️ Partial | ⚠️ Plugin-only | ✅ Yes (server) | ❌ No | | Relation presets (blog / ecommerce / social)| ✅ Built-in | ❌ No | ❌ No | ❌ No | ❌ No | | DB seeding | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No | | Extensible config | ✅ mocktail-cli.config.js | ⚠️ Partial | ⚠️ Partial | ⚠️ Partial | ⚠️ Manual only | | Enhanced relation detection | ✅ NEW | ❌ No | ❌ No | ❌ No | ❌ No | | Performance optimization | ✅ NEW | ❌ No | ❌ No | ❌ No | ❌ No | | Plugin system | ✅ NEW | ❌ No | ❌ No | ❌ No | ❌ No | | Better error messages | ✅ NEW | ❌ No | ❌ No | ❌ No | ❌ No | | Large dataset support | ✅ NEW | ❌ No | ❌ No | ❌ No | ❌ No | | Locale support (i18n) | ✅ NEW | ❌ No | ❌ No | ❌ No | ⚠️ Manual |

* faker-js supports faker.seed(...) for deterministic values, but it is not schema-aware and doesn’t handle relations automatically.

❤️ Mocktail-CLI uses @faker-js/faker internally for realistic field data — every record feels lifelike.

Takeaway:

• Mocktail-CLI is the only multi-schema, CLI-first tool that:
  • Supports Prisma, GraphQL, JSON Schema, and OpenAPI schemas
  • Auto-detects your schema files
  • Generates deep relation-safe mock data
  • Supports reproducible seeds
  • Offers multiple output formats & realistic presets
  • NEW in v1.3: Enhanced relation detection with confidence scoring
  • NEW in v1.3: Performance optimization for large datasets (1M+ records)
  • NEW in v1.3: Extensible plugin system with built-in plugins
  • NEW in v1.3: Better error messages with contextual information
  • NEW in v1.3: Enhanced UI/UX with progress tracking and better output
  • NEW in v1.4: Extensible type system with custom scalar support
  • NEW in v1.4: Advanced circular dependency resolution with smart strategies
  • NEW in v1.4.2: Internationalization support with 20+ locales for culturally appropriate data

Roadmap

• v1.0: ✅ CLI complete with flags for depth, output formats, custom config.
• v1.1: ✅ Schema auto-detection, advanced relation presets (blog, ecommerce, social).
• v1.2: ✅ Multi-schema support (Prisma, GraphQL, JSON Schema, OpenAPI)
• v1.3: ✅ Enhanced relation detection, performance optimization, plugin system, better error messages, UI/UX improvements
• v1.4: ✅ Extensible type system (custom scalars, formats), advanced circular dependency resolution
• v1.4.2: ✅ Internationalization support with 20+ locales for culturally appropriate data generation
• v1.5: 🚧 Integration with Mockilo for API mocking, seeding, and team workflows
• v1.6: 🔮 Machine learning-powered relation detection and smart data generation
• v1.7: 🔮 Advanced plugins ecosystem and web interface
• v2.0: 🔮 Real-time collaboration features and cloud integration

Contributing

We welcome PRs, bug reports, and feature ideas.

1. Fork the repo
2. Create a feature branch
3. Submit PR with tests and docs

License & Contact

License Update: From v1.1.1-beta.0, Mocktail-CLI is licensed under BSL-1.1. Older versions (<=1.1.0-beta.3) remain MIT.

• ☕🍹 Welcome to Mocktail CLI 🍹☕

Order up! Your personal code barista is here. Serving fresh, Prisma-aware mock data, shaken not stirred.