Musket CLI

About Musket CLI

Musket CLI is a framework-agnostic CLI framework designed to allow you build artisan-like CLI apps and for use in the H3ravel framework.

Installation

To use Musket CLI, you may install it by running:

npm install @h3ravel/musket
# or
pnpm add @h3ravel/musket
# or
yarn add @h3ravel/musket

Quick Setup

The base requirement fo setting up Musket CLI is an application class that it can bind itself to:

class Application {}

Once bound, Musket CLI will bind itself to the application class as musket and can be accessed as:

const app = new Application();

// Initialize Musket CLI here

console.log(app.musket);

Initialization

To initialize Musket CLI you can follow the example below:

import { Kernel } from 'h3ravel/musket';

const app = new Application();

Kernel.init(app);

The init method returs and instance of commanderjs's Command class allowing to further extend and customize your app if there is a need for that.

Passing Configuration

Musket allows passing a config object that alters it's behavior and provide some level of customizations

Kernel.init(app, {
  packages: ['@h3ravel/shared', '@h3ravel/support'],
  name: 'musket-cli',
  discoveryPaths: [path.join(process.cwd(), 'tests/Commands/*.ts')],
});

Advanced Initialization

If you need fine grained control with your initialization, Musket CLI exposes just the right methods to enable you do just that, when when initializing the CLI in this manner, the packages config property is completely ignored, as a work around, chain the setPackages method to the Kernel intance to achieve the same results.

import { Kernel } from 'h3ravel/musket';
import { TestCommand } from './TestCommand';

const app = new Application();

const instance = new Kernel(app)
  .setCwd(process.cwd())
  .setConfig({
    name: 'musket-cli',
    discoveryPaths: [path.join(process.cwd(), 'tests/Commands/*.ts')],
  })
  .setPackages([
    { name: '@h3ravel/shared', alias: 'Shared PKG' },
    '@h3ravel/support',
  ])
  .registerCommands([TestCommand])
  .bootstrap();

return await instance.run();

Creating Commands

Commands in Musket extend the base Command class and define a signature and handle() method.

Example:

import { Command } from '@h3ravel/musket';

export default class GreetCommand extends Command {
  protected signature = 'greet {name}';
  protected description = 'Display a personalized greeting.';

  async handle() {
    const name = this.argument('name');

    this.info(`Hello, ${name}!`);
  }
}

If your project uses discovery paths (via discoveryPaths), this command will be automatically registered.

Otherwise, you can manually register it in your application:

class Application {
  registeredCommands = [GreetCommand];
}

await Kernel.init(app);

// OR

await Kernel.init(app, {
  baseCommands: [GreetCommand, BuildCommand],
});

Running Commands

Once your CLI is compiled or built, you can run commands via:

node dist/cli.js greet Legacy

Output:

Hello, Legacy!

Documentation

The full musket documentation is available Here

Contributing

Thank you for considering contributing to the H3ravel framework! The Contribution Guide can be found in the H3ravel documentation and will provide you with all the information you need to get started.

Code of Conduct

In order to ensure that the H3ravel community is welcoming to all, please review and abide by the Code of Conduct.

Security Vulnerabilities

If you discover a security vulnerability within H3ravel, please send an e-mail to Legacy via hamzas.legacy@toneflix.ng. All security vulnerabilities will be promptly addressed.

License

The H3ravel framework is open-sourced software licensed under the MIT license.