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/application.luhn: independent application identity and owned modules
• luhn/: LUHN declarations stored in the schema derived from the application name
• 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]
luhn compile --plugin @agility-luhn/iam
luhn compile --all-plugins

Options:

• -o, --out <dir> - Output directory (default: ./src/luhn/generated)
• --plugin <package> - Include an installed LUHN plugin; repeat for multiple plugins
• --all-plugins - Include direct dependencies marked with luhn.plugin: true
• --plugin-manifest <path> - Include plugins and application ownership from luhn-plugin.json descriptors
• --no-typescript - Do not generate TypeScript artifacts
• --no-openapi - Do not generate OpenAPI
• --no-database-schema - Do not generate database schema
• --no-metadata - Do not generate metadata
• --no-canonical-mapping - Do not generate canonical mapping

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 routes

Discover Business routes from .luhn files for menu, permission, and action catalogs. The command uses the compiler AST Application as its root, includes the modules listed by that application, and emits routes for their Business declarations. Record, Service, View, Configuration, and Ui declarations do not create routes.

luhn routes                  # Human-readable output grouped by module
luhn routes --json           # JSON for integration
luhn routes -m administrador # Filter by module key
luhn routes --plugin @agility-luhn/iam # Include an installed plugin
luhn routes --all-plugins    # Include all installed LUHN plugins
luhn routes --describe       # Output the JSON contract description
luhn routes --spec           # Alias for --describe

Use --plugin <package> once for each installed LUHN plugin that contributes routes. The command imports the plugin only to read luhnDirs, then parses its .luhn files together with the application files. It does not create a server, connect to a database, or run the plugin install hook.

luhn routes --json --plugin @agility-luhn/iam --plugin @agility-luhn/cron

Use --all-plugins to include every direct dependency or optionalDependency declared as a LUHN plugin. This mode reads package manifests only; it does not import or execute plugin code. A plugin must expose the following metadata in its package.json:

{
  "luhn": {
    "plugin": true,
    "luhnDirs": ["luhn"]
  }
}

luhn routes --all-plugins --json

The JSON output has the application at the root, its modules, and each module's Business routes with their standard actions:

{
  "application": {
    "key": "erp",
    "name": "ERP",
    "modules": [
      {
        "key": "administrador",
        "name": "Administrador",
        "order": 0,
        "active": true,
        "routes": [
          {
            "key": "administrador.agendamento",
            "name": "Agendamentos",
            "display": "Agendamentos",
            "path": "/api/administrador/agendamento",
            "kind": "BUSINESS",
            "visible": true,
            "order": 0,
            "active": true,
            "actions": [
              {
                "key": "administrador.agendamento.findAll",
                "name": "Listar",
                "display": "Listar Agendamentos",
                "path": "/api/administrador/agendamento/$query",
                "kind": "LIST",
                "parentKey": "administrador.agendamento",
                "method": "POST",
                "visible": true,
                "order": 3,
                "active": true
              }
            ]
          }
        ]
      }
    ]
  }
}

Each action has parentKey equal to the owning Business route key.

| Kind | Key suffix | HTTP method | Path suffix | | --- | --- | --- | --- | | READ | .findById | GET | /{id} | | CREATE | .create | POST | base path | | LIST | .findAll | POST | /$query | | UPDATE | .update | PUT | /{id} | | DELETE | .delete | DELETE | /{id} |

Application and module name values use their AST titles when available. Module active is read from its Module declaration. Modules not listed in Application.modules and their Businesses are ignored. Module and route order follow declaration order. icon is not emitted because the current LUHN AST has no icon metadata for modules or Businesses.

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