CLI Commands

The laramail package includes a powerful CLI tool for queue management, email preview, code generation, and configuration validation.

Installation

The CLI is automatically available after installing the package:

npm install laramail

For styled output, install the optional dependency:

Chalk (optional)

npm install chalk

Configuration

The CLI automatically detects configuration files in your project root:

laramail.config.ts (TypeScript, recommended)
laramail.config.js (JavaScript)
laramail.config.mjs (ES Module)
laramail.config.cjs (CommonJS)

Example Configuration

// laramail.config.ts
import { defineConfig } from 'laramail';

export default defineConfig({
  default: 'smtp',
  from: {
    address: 'noreply@example.com',
    name: 'My App',
  },
  mailers: {
    smtp: {
      driver: 'smtp',
      host: process.env.SMTP_HOST,
      port: 587,
      auth: {
        user: process.env.SMTP_USER,
        pass: process.env.SMTP_PASS,
      },
    },
  },
  queue: {
    driver: 'bullmq',
    connection: { host: 'localhost', port: 6379 },
  },
});

The defineConfig helper provides TypeScript autocomplete for your configuration.

Commands

Queue Commands

`queue:work`

Start processing queued emails.

npx laramail queue:work [options]

Options:

Option	Description	Default
`-q, --queue <name>`	Queue name to process	`mail`
`-c, --concurrency <n>`	Number of concurrent jobs	`1`
`--config <path>`	Path to config file	Auto-detected

Example:

# Process the default mail queue
npx laramail queue:work

# Process with 5 concurrent workers
npx laramail queue:work --concurrency 5

# Process a specific queue
npx laramail queue:work --queue notifications

`queue:status`

Show queue job counts and status.

npx laramail queue:status [options]

Options:

Option	Description	Default
`-q, --queue <name>`	Queue name to check	`mail`
`--config <path>`	Path to config file	Auto-detected

Example:

npx laramail queue:status

Output:

Queue Status: mail
================

Waiting:   15
Active:    2
Completed: 1,234
Failed:    3
Delayed:   5
Paused:    0

Total Jobs: 1,259

`queue:clear`

Clear jobs from the queue by status.

npx laramail queue:clear [options]

Options:

Option	Description	Default
`-q, --queue <name>`	Queue name	`mail`
`-s, --status <status>`	Job status to clear	`failed`
`-f, --force`	Skip confirmation prompt	`false`
`--config <path>`	Path to config file	Auto-detected

Valid statuses: completed, failed, delayed, waiting (BullMQ only)

Example:

# Clear failed jobs (with confirmation)
npx laramail queue:clear --status failed

# Clear completed jobs without confirmation
npx laramail queue:clear --status completed --force

# Clear delayed jobs from a specific queue
npx laramail queue:clear --queue notifications --status delayed

`queue:retry`

Retry failed jobs in the queue.

npx laramail queue:retry [options]

Options:

Option	Description	Default
`-q, --queue <name>`	Queue name	`mail`
`-l, --limit <n>`	Maximum jobs to retry	All failed jobs
`--config <path>`	Path to config file	Auto-detected

Example:

# Retry all failed jobs
npx laramail queue:retry

# Retry up to 10 failed jobs
npx laramail queue:retry --limit 10

Email Commands

`preview`

Preview an email in your browser without sending.

npx laramail preview [options]

Options:

Option	Description	Default
`-m, --mailable <path>`	Path to Mailable class file	Required
`-o, --output <path>`	Save HTML to file instead of browser	-
`--config <path>`	Path to config file	Auto-detected

Example:

# Preview a Mailable in browser
npx laramail preview --mailable ./src/mail/WelcomeEmail.ts

# Save preview to file
npx laramail preview --mailable ./src/mail/WelcomeEmail.ts --output preview.html

Note: Requires the open package for browser preview:

Open (for browser preview)

npm install open

`send:test`

Send a test email to verify your configuration.

npx laramail send:test [options]

Options:

Option	Description	Default
`-t, --to <email>`	Recipient email address	Required
`--mailer <name>`	Mailer to use	Default mailer
`--config <path>`	Path to config file	Auto-detected

Example:

# Send test email to yourself
npx laramail send:test --to your@email.com

# Test a specific mailer
npx laramail send:test --to your@email.com --mailer sendgrid

Code Generation

`make:mailable`

Generate a new Mailable class.

npx laramail make:mailable <name> [options]

Arguments:

Argument	Description
`name`	Name of the Mailable class (e.g., `WelcomeEmail`)

Options:

Option	Description	Default
`-d, --dir <path>`	Output directory	`./src/mail`
`--markdown`	Use MarkdownMailable base class	`false`
`--template <name>`	Include template method with name	-

Example:

# Generate a basic Mailable
npx laramail make:mailable WelcomeEmail

# Generate in a custom directory
npx laramail make:mailable OrderConfirmation --dir ./src/emails

# Generate a MarkdownMailable
npx laramail make:mailable NewsletterEmail --markdown

# Generate with template support
npx laramail make:mailable InvoiceEmail --template invoice

Generated file (src/mail/WelcomeEmail.ts):

import { Mailable } from 'laramail';

export class WelcomeEmail extends Mailable {
  constructor() {
    super();
  }

  build(): this {
    return this
      .subject('Welcome Email')
      .html('<h1>Welcome!</h1><p>Thank you for joining.</p>');
  }
}

Configuration

`config:check`

Validate your mail configuration.

npx laramail config:check [options]

Options:

Option	Description	Default
`--config <path>`	Path to config file	Auto-detected
`--test`	Test provider connections	`false`

Example:

# Validate configuration
npx laramail config:check

# Validate and test provider connections
npx laramail config:check --test

Output:

Configuration Check
===================

Config file found: /path/to/laramail.config.ts
Configuration loaded successfully

Validating configuration...

Default mailer: smtp
From address: My App <noreply@example.com>

Configured mailers (2):
  smtp (default): smtp
  sendgrid: sendgrid

Queue configured: bullmq
Templates configured: handlebars

Configuration is valid!

Global Options

All commands support the following global options:

Option	Description
`--config <path>`	Specify a custom config file path
`-h, --help`	Show help for a command
`-V, --version`	Show CLI version

Programmatic Usage

You can also use CLI functionality programmatically:

import { QueueManager } from 'laramail';

// Get queue status
const manager = new QueueManager(config.queue);
const counts = await manager.getJobCounts('mail');
console.log(counts);
// { waiting: 10, active: 2, completed: 100, failed: 5, delayed: 3, paused: 0 }

// Clear failed jobs
await manager.clear('mail', 'failed');

// Retry failed jobs
const retriedCount = await manager.retryFailed('mail', 10);

Troubleshooting

Config file not found

Ensure your config file is in the project root and uses one of the supported names:

laramail.config.ts
laramail.config.js
laramail.config.mjs
laramail.config.cjs

Queue commands fail

Make sure Redis is running and your queue configuration is correct:

queue: {
  driver: 'bullmq', // or 'bull'
  connection: { host: 'localhost', port: 6379 },
}

Preview doesn't open browser

Install the open package:

npm install open

Or use the --output flag to save to a file instead.

Styled output not showing

Install chalk for colored output:

npm install chalk

The CLI works without chalk but will show plain text output.