LUHN CLI

Official Command-Line Interface for the LUHN Framework - A modern framework for building scalable applications with type-safe database operations and automatic code generation.

Features

• ✨ Project Initialization - Bootstrap a new LUHN project with interactive setup
• 🏗️ Compilation - Transform DSL files into TypeScript and database schemas
• 📦 Module Discovery - List all modules, entities, and their attributes
• 🗄️ Database Management - Migrate, sync, and introspect databases
• 🚀 Development Server - Start your application server with hot-reload support

Installation

Install LUHN CLI globally:

npm install -g @agility-luhn/cli
pnpm add -g @agility-luhn/cli
yarn global add @agility-luhn/cli

Or use it directly with npx:

npx @agility-luhn/cli --version

Quick Start

1. Create a New Project

luhn init
# or
luhn create

The CLI will guide you through an interactive setup asking for project name, description, and package manager.

2. Define Your Business Logic

Create .luhn files in the luhn/ directory to define your entities and services.

3. Compile Your Project

luhn compile

Generates TypeScript types, database migrations, and schema files.

4. Manage Your Database

luhn db migrate    # Apply pending migrations
luhn db sync       # Sync schema with database
luhn db introspect # Inspect existing database

5. Start Development Server

luhn serve         # Start development server
luhn serve --watch # With file watching

Commands

luhn init / luhn create

Initialize a new LUHN project.

luhn init [targetDir]
luhn create my-project

Options:

• --template <name> - Use specific template (default, minimal, advanced)
• --no-install - Skip dependency installation
• --force - Overwrite existing directory

luhn plugin create

Bootstrap a new LUHN plugin project.

luhn plugin create [targetDir]

The generated plugin includes:

• src/index.ts: plugin entrypoint exporting a LuhnPlugin
• luhn/: LUHN declarations contributed by the plugin
• tsconfig.json, package.json, release configuration
• GitHub Actions workflows for build and release

luhn plugin pack

Build and pack a LUHN plugin into a distributable .tgz file.

luhn plugin pack [pluginDir]

The output file <name>-<version>.tgz can be distributed or loaded by the LUHN runtime:

await createLuhnServer({
  luhnDir: './luhn',
  plugins: [
    { type: 'tarball', path: './plugins/my-plugin-1.0.0.tgz' }
  ]
});

Options:

• --no-build - Skip the build step

luhn compile

Compile LUHN DSL files to artifacts (TypeScript, schemas, migrations).

luhn compile [sourceDir]

Options:

• --output <dir> - Output directory (default: ./src/generated)
• --watch - Watch for changes and recompile
• --strict - Strict validation mode

luhn list / luhn ls

Discover and list all modules, entities, and their attributes.

luhn list              # List all modules
luhn list --full       # Show all attributes
luhn list -m auth      # Filter by module
luhn list -e User      # Filter by entity
luhn list --json       # JSON output

Options:

• -m, --module <name> - Filter by module name
• -e, --entity <name> - Filter by entity name
• -f, --full - Show complete attribute details
• --json - Output as JSON

luhn db

Manage database operations.

luhn db migrate    # Apply pending migrations
luhn db sync       # Sync schema with database
luhn db introspect # Inspect existing database
luhn db create     # Create database
luhn db reset      # Reset database (development only)

Options:

• --connection <string> - Database connection string
• --force - Force operation without confirmation
• --dry-run - Show what would be done

luhn serve

Start the development server.

luhn serve

Options:

• -p, --port <number> - Server port (default: 3000)
• -w, --watch - Watch for file changes
• --debug - Run with debug logging
• --no-reload - Disable hot-reload

Environment Variables

Database

• DB_CONNECTION or DATABASE_URL - PostgreSQL connection string (required for luhn serve and luhn db).
• POSTGRES_CONNECTION_STRING - Alternative PostgreSQL connection string.

Object Storage (storage fields)

When using fields of type storage, the runtime uploads files to an S3-compatible object store (MinIO by default). Configure it with:

• STORAGE_ENDPOINT - Object storage host (e.g. localhost).
• STORAGE_PORT - Object storage port (e.g. 9000).
• STORAGE_USE_SSL - true or false.
• STORAGE_ACCESS_KEY - Access key.
• STORAGE_SECRET_KEY - Secret key.
• STORAGE_BUCKET - Default bucket for uploads.
• STORAGE_PRESIGNED_URL_EXPIRY_SECONDS - Optional expiry for download URLs (default: 3600).

Files are sent to the API as base64 data URIs and replaced by se://<bucket>/<key> URIs before persistence. Use GET /storage/<bucket>/<key> to obtain a presigned download URL.

License

MIT © Agility Solutions

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions