@kysera/cli

Comprehensive command-line interface for Kysera - A production-ready type-safe data access toolkit for TypeScript with enterprise-grade features.

🚀 Features

• 🗄️ Database Management - Complete lifecycle management with PostgreSQL, MySQL, and SQLite support
• 🔄 Migration System - Robust migration creation, execution, and rollback with version control
• ⚙️ Code Generation - Generate type-safe models, repositories, and CRUD operations
• 📊 Health Monitoring - Real-time database health checks and performance metrics
• 📝 Audit Logging - Comprehensive audit trail with history tracking and restoration
• 🧪 Test Utilities - Test environment setup, fixtures, and intelligent data seeding
• 🔌 Plugin System - Extensible architecture with plugin discovery and configuration
• ⚡ Performance - Lazy loading, caching, connection pooling, and query optimization
• 🎯 Developer Experience - Verbose/quiet modes, dry-run support, progress indicators

📦 Installation

# NPM
npm install -g @kysera/cli

# PNPM (recommended)
pnpm add -g @kysera/cli

# Yarn
yarn global add @kysera/cli

# Bun
bun add -g @kysera/cli

# Project-specific installation
pnpm add -D @kysera/cli

🛠 Quick Start

# Initialize a new project
kysera init my-app --dialect postgres --typescript

# Create and run migrations
kysera migrate create add_users_table
kysera migrate up

# Generate models and repositories
kysera generate model User --table users
kysera generate repository User --with-validation

# Generate complete CRUD with API
kysera generate crud Post --api --tests

# Check database health
kysera health check

🎯 Shell Completions

Kysera CLI provides shell completion scripts for Bash, Zsh, and Fish shells to enhance your development experience with tab completion for commands, subcommands, and options.

Bash

System-wide installation:

sudo cp scripts/completions/kysera.bash /etc/bash_completion.d/kysera
# or on macOS with Homebrew:
sudo cp scripts/completions/kysera.bash /usr/local/etc/bash_completion.d/kysera

User installation:

# Add to your ~/.bashrc or ~/.bash_profile:
source /path/to/kysera-cli/scripts/completions/kysera.bash

Then reload your shell:

source ~/.bashrc

Zsh

System-wide installation:

sudo cp scripts/completions/kysera.zsh /usr/local/share/zsh/site-functions/_kysera

User installation:

# Create completions directory if it doesn't exist
mkdir -p ~/.zsh/completions

# Copy the completion file
cp scripts/completions/kysera.zsh ~/.zsh/completions/_kysera

# Add to your ~/.zshrc:
fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinit

Then reload your shell:

source ~/.zshrc

Fish

Installation:

# User installation (recommended)
cp scripts/completions/kysera.fish ~/.config/fish/completions/

# System-wide installation
sudo cp scripts/completions/kysera.fish /usr/share/fish/vendor_completions.d/

Fish will automatically load completions - no need to reload.

Features

The completion scripts provide intelligent suggestions for:

• Commands: All main commands (init, migrate, generate, db, etc.)
• Subcommands: Context-aware subcommand completion (e.g., migrate up, generate model)
• Options: All global and command-specific flags
• Values: Predefined values for options like --dialect, --validation, --strategy
• Files: File path completion for config files and output directories

Example Usage

# Type and press TAB:
kysera <TAB>
# Shows: init migrate generate db health audit debug query repository test plugin help

kysera migrate <TAB>
# Shows: create up down status list reset fresh rollback

kysera generate --validation <TAB>
# Shows: zod yup joi none

kysera --config <TAB>
# Shows: file path completions for .ts, .js, .json files

📚 Command Overview

| Command | Description | Aliases | | ------------ | -------------------------------- | ------- | | init | Initialize a new Kysera project | | | migrate | Database migration management | | | generate | Code generation utilities | g | | db | Database management tools | | | health | Health monitoring and metrics | | | audit | Audit logging and history | | | query | Query analysis and utilities | | | test | Test environment management | | | plugin | Plugin management | | | debug | Debug and diagnostic tools | | | repository | Repository pattern utilities | | | hello | Test command to verify CLI setup | | | stats | Show CLI performance statistics | |

Command Aliases

Some commands support short aliases for faster typing:

# Generate command has 'g' alias
kysera g model User
kysera generate model User  # equivalent

# Both commands do the same thing
kysera g repository Post
kysera generate repository Post  # equivalent

⚙️ Configuration

Configuration Files

Kysera CLI uses cosmiconfig for flexible configuration loading. The CLI will automatically search for configuration in the following locations (in order of priority):

1. kysera.config.ts (recommended for TypeScript projects)
2. kysera.config.js
3. kysera.config.mjs
4. kysera.config.cjs
5. kysera.config.json
6. .kyserarc.ts
7. .kyserarc.js
8. .kyserarc.json

You can also specify a custom config file using the --config flag:

kysera migrate up --config ./custom-config.ts

TypeScript Configuration

Create kysera.config.ts in your project root (recommended):

import { defineConfig } from '@kysera/cli'

export default defineConfig({
  database: {
    dialect: 'postgres',
    host: process.env.DB_HOST || 'localhost',
    port: parseInt(process.env.DB_PORT || '5432'),
    database: process.env.DB_NAME || 'myapp',
    user: process.env.DB_USER || 'postgres',
    password: process.env.DB_PASSWORD,
    pool: { min: 2, max: 10 }
  },

  migrations: {
    directory: './migrations',
    tableName: 'kysera_migrations',
    timezone: 'UTC'
  },

  generation: {
    outputDir: './src/generated',
    typescript: true,
    validation: 'zod'
  },

  plugins: {
    '@kysera/soft-delete': { enabled: true },
    '@kysera/timestamps': { enabled: true },
    '@kysera/audit': { enabled: true }
  }
})

JSON Configuration

For simpler projects, you can use kysera.config.json:

{
  "database": {
    "dialect": "postgres",
    "host": "localhost",
    "port": 5432,
    "database": "myapp"
  },
  "migrations": {
    "directory": "./migrations"
  }
}

🎯 Global Options

All commands support these global options:

| Option | Description | Default | | --------------------- | --------------------------------------------------- | ------------- | | --verbose | Enable detailed output with debug information | false | | -q, --quiet | Suppress non-essential output | false | | --dry-run | Preview changes without executing | false | | --config <path> | Path to custom configuration file | Auto-detect | | --json | Output results as JSON | false | | --no-color | Disable colored output | false | | --env <environment> | Set environment (development/production/test) | development | | --stats | Show performance statistics after command execution | false |

Examples

# Verbose output with debug information
kysera migrate up --verbose

# Quiet mode - minimal output
kysera generate model User --quiet

# Preview changes without executing
kysera db reset --dry-run

# Use custom config file
kysera migrate up --config ./config/db.ts

# JSON output for scripting
kysera health check --json

# Disable colors for CI/CD
kysera test setup --no-color

# Set environment
kysera migrate up --env production

# Show performance stats
kysera generate crud Post --stats

🛠 Built-in Utility Commands

Hello Command

Test command to verify CLI setup and configuration:

# Basic hello
kysera hello
# Output: Hello, World! 👋

# With custom name
kysera hello --name John
# Output: Hello, John! 👋

# With verbose output
kysera hello --verbose
# Output:
# Hello, World! 👋
# CLI is working correctly!

Stats Command

Show CLI performance statistics including command load times, cache hit rates, and usage patterns:

kysera stats

Example output:

CLI Performance Statistics
────────────────────────────────────────────────────────────
Command Load Times:
  migrate: 45ms (used 23 times)
  generate: 38ms (used 15 times)
  health: 12ms (used 8 times)

Cache Hit Rate: 85%

Most Used Commands:
  1. migrate
  2. generate
  3. health
────────────────────────────────────────────────────────────
Startup time: 124ms

The stats command helps you:

• Identify frequently used commands (which are preloaded for faster startup)
• Monitor cache efficiency
• Track command load times
• Optimize CLI performance

🧪 Testing Support

# Setup test environment
kysera test setup --env test

# Seed test data
kysera test seed --count 1000 --strategy realistic

# Load fixtures
kysera test fixtures users.json posts.yaml

# Teardown
kysera test teardown --env test --force

Docker Support

# Start test databases
docker compose -f docker-compose.test.yml up -d

# Run multi-database tests
TEST_POSTGRES=true TEST_MYSQL=true pnpm test

🚀 Advanced Features

Progress Indicators

kysera migrate up
✓ Running migration: 001_create_users.ts
⠋ Running migration: 002_create_posts.ts [45%]

Dry Run Mode

kysera migrate up --dry-run
[DRY RUN] Would execute:
  - 001_create_users.ts
  - 002_create_posts.ts

Performance Monitoring

kysera stats
Command Load Times:
  migrate: 45ms (23 uses)
Cache Hit Rate: 85%

📖 Documentation

• Full Documentation
• API Reference
• Migration Guide
• Plugin Development

📄 License

MIT © Kysera Team