Brocli

Brocli provides builder functions to define typed CLI arguments.

Core Builders

• string(name?: string): Defines a string option. Passed as --option=value or --option value. If name is not provided, it defaults to the key name.
• number(name?: string): Defines a number option. Passed as --option=value or --option value.
• boolean(name?: string): Defines a boolean flag. Passed as --option.
• positional(displayName?: string): Defines a positional option. Passed as command value.

Option Extensions

All builders support the following methods to refine behavior:

• .alias(...aliases: string[]): Adds aliases (e.g., .alias('f')).
• .desc(description: string): Sets the description for the help command.
• .required(): Makes the option mandatory; the app will error if it's missing.
• .default(value: string | boolean): Sets a default value.
• .hidden(): Hides the option from the help output.
• .enum(values: [string, ...string[]]): Restricts string values to a specific set.
• .int(): Ensures a number is an integer.
• .min(value: number) / .max(value: number): Sets numeric boundaries.

Naming Convention: If a name is one character long, it is automatically prefixed with -. If longer, it uses --. To force a single hyphen on a long name, pass it explicitly: string('-longname').

import { string, boolean } from "@drizzle-team/brocli";

const options = {
  dialect: string().enum("postgresql", "mysql", "sqlite"),
  databaseSchema: string().required(),
  databaseUrl: string().required(),
  strict: boolean().default(false),
};

The run() function is the entry point that starts the command execution loop. It takes your collection of commands and a configuration object.

Key Configuration Options

• name: The name used to invoke the application in help/usage examples.
• description: Global description of your app.
• version: String or handler for the app version.
• globals: An object of global options available to all commands via the hook.
• theme(event: BroCliEvent): A function to customize how messages (like commandHelp or unknownError) are printed. Return true to indicate you handled the event, or false to fall back to the default theme.
• hook(event, command, globals): Executes code before or after every command's transform and handler execution.
• omitKeysOfUndefinedOptions: If true, undefined options are not passed to transform or handler.
• argSource: The array of arguments to parse (defaults to process.argv).

import { command, run, string, boolean, type TypeOf } from '@drizzle-team/brocli'

const commands: Command[] = [
  command({
    name: 'command',
    options: { opt1: string() },
    handler: (opts) => { /* ... */ },
  })
];

run(commands, {
    name: 'mysoft',
    description: 'MySoft CLI',
    version: '1.0.0',
    globals: {
        flag: boolean('gflag').description('Global flag').default(false)
    },
    hook: (event, command, globals) => {
        if(event === 'before') console.log(`Command '${command.name}' started with flag ${globals.flag}`)
        if(event === 'after') console.log(`Command '${command.name}' successfully finished it's work with flag ${globals.flag}`)
    }
})

Use the command() function to define a CLI command. A command can include a name, aliases, descriptions, options, a transform hook for preprocessing, and a handler for the main logic. If a command has subcommands, it does not require a handler (the help text will be shown instead).

Note: A command cannot have both subcommands and positional options simultaneously.

import { command, type Command, string, boolean, type TypeOf } from '@drizzle-team/brocli'

const commandOptions = {
    opt1: string(),
    opt2: boolean('flag').alias('f'),
}

const commands: Command[] = []

commands.push(command({
    name: 'command', 
    aliases: ['c', 'cmd'],
    desc: 'Description goes here',
    shortDesc: 'Short description',
    hidden: false,
    options: commandOptions,
    transform: (options) => {
        // Preprocess options here...
        return processedOptions
    },
    handler: (processedOptions) => {
        // Your logic goes here...
    },
    help: () => 'This command works like this: ...',
    subcommands: [
        command(
            // You can define subcommands like this
        )
    ]
}));

When defining handlers separately from the command() call, you need to ensure type safety for the options object. You can achieve this in two ways:

1. Using the TypeOf utility

Define your options object first, then use TypeOf to extract its type for your handler function.

import { string, boolean, type TypeOf } from '@drizzle-team/brocli'

const commandOptions = {
    opt1: string(),
    opt2: boolean('flag').alias('f'),
}

export const commandHandler = (options: TypeOf<typeof commandOptions>) => {
    // Your logic goes here...
}

2. Using the handler() wrapper

Wrap your logic in the handler() function, which automatically handles the type inference based on the provided options schema.

import { string, boolean, handler } from '@drizzle-team/brocli'

const commandOptions = {
    opt1: string(),
    opt2: boolean('flag').alias('f'),
}

export const commandHandler = handler(commandOptions, (options) => {
    // Your logic goes here...
});

Pass a BroCliConfig object to run() to customize the CLI behavior.

Key Configuration Options:

• name: The name of the CLI.
• description: A description of the CLI.
• argSource: The array of arguments to parse (defaults to process.argv).
• help: A string or a function (options) => void to define help output.
• version: A string or a function (options) => void to define version output.
• globals: Global options available to all commands.
• omitKeysOfUndefinedOptions: If true, undefined options are removed from the resulting options object.
• hook: A lifecycle hook called before and after a command handler executes.
• theme: An EventHandler to customize how the CLI renders output (help, errors, etc.).
• noExit: If true, prevents the process from exiting on errors (useful for testing).

await run(commands, {
  name: 'my-app',
  description: 'My awesome app',
  omitKeysOfUndefinedOptions: true,
  hook: (event, command, options) => {
    if (event === 'before') console.log(`Executing ${command.name}...`);
  },
});