@lara-node/console

Artisan CLI — command runner, custom command base class, and cron scheduler for Lara-Node apps.

Installation

pnpm add @lara-node/console

The artisan binary is available at node_modules/.bin/artisan after installation.

Quick Start

# Start the dev server
node artisan serve

# Generate an application key
node artisan key:generate

# Run database migrations
node artisan migrate

Built-in Commands

Server

node artisan serve [--port=3000] [--host=localhost]

Key management

node artisan key:generate   # writes APP_KEY to .env

Migrations

node artisan migrate               # run all pending migrations
node artisan migrate:fresh         # drop all tables then re-run all migrations
node artisan migrate:rollback      # roll back the most recent migration batch

Cache

node artisan cache:clear              # clear all cached values
node artisan cache:list               # list all cache keys
node artisan cache:get <key>          # retrieve a value by key
node artisan cache:set <key> <value>  # store a value
node artisan cache:forget <key>       # delete a key
node artisan cache:has <key>          # check key existence (exit 0 = exists)
node artisan cache:driver             # show the active cache driver

Queue

node artisan queue:work [--connection=redis] [--queue=default] [--tries=3] [--timeout=60]
node artisan queue:failed          # list failed jobs
node artisan queue:retry <id>      # retry a specific failed job
node artisan queue:flush           # delete all failed jobs

Routes

node artisan route:list   # print a table of all registered routes

Events

node artisan event:list   # list all registered events and their listeners

Horizon

node artisan horizon:start   # start Horizon supervisor
node artisan horizon:pause   # pause all workers
node artisan horizon:resume  # resume all workers
node artisan horizon:status  # show worker status

Documentation

node artisan docs:generate   # write openapi.json to the project root

Publishing

node artisan vendor:publish   # copy package config stubs to config/

Broadcasting

node artisan broadcast:channels   # list all registered broadcast channels

Scheduler

node artisan schedule:run   # execute all due scheduled tasks immediately

Custom Commands

Commands in app/Console/Commands/

The generated ConsoleKernel auto-discovers every Command subclass exported from files in app/Console/Commands/. Just create a file there — no manual registration needed.

// src/app/Console/Commands/GreetCommand.ts
import { Command } from '@lara-node/console';
import type { ArgumentsCamelCase } from 'yargs';

export class GreetCommand extends Command {
  protected signature = 'greet';
  protected description = 'Greet a user by name';
  protected arguments = {
    name: { type: 'string' as const, description: 'The name to greet' },
  };
  protected options = {
    caps: { type: 'boolean' as const, description: 'Print name in uppercase', default: false },
  };

  async handle(args: ArgumentsCamelCase): Promise<void> {
    const name = args.name as string;
    const caps = args.caps as boolean;
    this.info(`Hello, ${caps ? name.toUpperCase() : name}!`);
  }
}

Commands outside app/Console/Commands/

For commands defined elsewhere (e.g. inside a package or a different directory), decorate the class with @Artisan(). It will be registered automatically when its module is imported.

this.argument("name"); // positional argument value
this.option("caps"); // boolean flag value
this.option("port"); // option with value (--port=8080)

this.info("message"); // green output
this.error("message"); // red output (also to stderr)
this.warn("message"); // yellow output
this.line("message"); // plain output
this.comment("message"); // dim comment line
this.newLine(); // blank line
import type { ArgumentsCamelCase } from 'yargs';

@Artisan()
export class SendNewsletterCommand extends Command {
  protected signature = 'newsletter:send';
  protected description = 'Send the daily newsletter';

  async handle(args: ArgumentsCamelCase): Promise<void> {
    this.info('Sending newsletter...');
    // ...
  }
}

Import the file somewhere in your bootstrap path so the decorator fires before artisan boots.

ConsoleKernel

The scaffolded ConsoleKernel wires both mechanisms together:

// src/app/Console/Kernel.ts
import path from 'path';
import { Kernel as BaseKernel } from '@lara-node/console';

export class ConsoleKernel extends BaseKernel {
  async boot(): Promise<void> {
    this.discoverCommands(path.join(__dirname, 'Commands'));
    await super.boot();
  }
}

To manually register additional commands you can also call this.addCommand(MyCommand) inside boot().

Output helpers

this.info('message')           // green output
this.error('message')          // red output (also to stderr)
this.warn('message')           // yellow output
this.line('message')           // plain output
this.comment('message')        // dim comment line
this.newLine()                 // blank line

const answer = await this.ask("What is your name?");
const secret = await this.secret("Enter password:");
const confirmed = await this.confirm("Are you sure?");
const choice = await this.choice("Pick a driver", ["file", "redis", "database"]);

Registering commands

// src/Console/Kernel.ts
import { Kernel } from "@lara-node/console";
import { GreetCommand } from "./GreetCommand";

export class AppKernel extends Kernel {
  protected commands = [GreetCommand];
}

Then point the artisan entrypoint at your kernel:

// artisan.ts
import { AppKernel } from "./src/Console/Kernel";
AppKernel.handle();

Cron Scheduler

Override schedule() in your ConsoleKernel subclass to register recurring tasks.

import path from 'path';
import { Kernel as BaseKernel } from '@lara-node/console';

export class ConsoleKernel extends BaseKernel {
  async boot(): Promise<void> {
    this.discoverCommands(path.join(__dirname, 'Commands'));
    await super.boot();
  }

  protected schedule(): void {
    // Run a closure
    this._scheduler.call(() => console.log("Every minute")).everyMinute();

    // Run a command
    this._scheduler.command("cache:clear").daily().withoutOverlapping().onOneServer();

    // Custom cron expression
    this._scheduler
      .call(async () => {
        await sendWeeklyReport();
      })
      .cron("0 8 * * 1") // 08:00 every Monday
      .timezone("UTC");
  }
}

Available frequency helpers: .everyMinute(), .everyFiveMinutes(), .everyTenMinutes(), .everyFifteenMinutes(), .everyThirtyMinutes(), .hourly(), .daily(), .dailyAt('13:00'), .weekdays(), .weekends(), .weekly(), .monthly(), .cron(expr).

Run due tasks:

node artisan schedule:run

Set this up as a system cron to poll every minute:

* * * * * cd /var/www/my-api && node artisan schedule:run >> /dev/null 2>&1

Environment Variables

| Variable | Default | Description | | -------- | ----------- | -------------------------------- | | PORT | 3000 | Port used by the serve command | | HOST | localhost | Host used by the serve command |