Documentation

Documentation / zerotal / index / CommandRunner

Class: CommandRunner

Defined in: packages/core/src/command/CommandRunner.ts:218

Registry and dispatcher for console commands.

Holds the map of command name (and aliases) to command class, parses argv into the arguments and flags each command declares, and runs the matched command — either as a CLI process via CommandRunner.run (which calls process.exit) or in-process via CommandRunner.callInProcess (which captures output and returns a status code). Commands can be registered as classes (CommandRunner.register), from closure-style definitions (CommandRunner.command), as lazy thunks (CommandRunner.registerLazy), or discovered from a directory (CommandRunner.discover).

Example

const runner = new CommandRunner(app);

// Register a command class…
runner.register(GreetCommand, ["hello"]);

// …or define one inline with an Artisan-style signature.
runner.command({
  signature: "cache:clear {--tag=}",
  description: "Clear the application cache",
  handle: async (params, command) => {
    command.info(`Clearing ${params["tag"] ?? "all"} cache…`);
  },
});

// Dispatch the argv the CLI entry point received.
await runner.run(process.argv.slice(2)); // e.g. `bun zt greet Ada`

Constructors

Constructor

new CommandRunner(_app): CommandRunner

Defined in: packages/core/src/command/CommandRunner.ts:221

Parameters

_app

Application

Returns

CommandRunner

Methods

register()

register(Cmd, aliases?): void

Defined in: packages/core/src/command/CommandRunner.ts:226

Register a command class under its name and any aliases.

Parameters

Cmd

CommandStatic

aliases?

string[] = []

Returns

void

registerAll()

registerAll(commandClasses): void

Defined in: packages/core/src/command/CommandRunner.ts:232

Register several command classes at once.

Parameters

commandClasses

CommandStatic[]

Returns

void

command()

command(definition, aliases?): CommandStatic

Defined in: packages/core/src/command/CommandRunner.ts:237

Build and register a command from a closure-style definition.

Parameters

definition

CommandDefinition

aliases?

string[] = []

Returns

CommandStatic

registerCommand()

registerCommand(definition, aliases?): CommandStatic

Defined in: packages/core/src/command/CommandRunner.ts:244

Alias for CommandRunner.command.

Parameters

definition

CommandDefinition

aliases?

string[] = []

Returns

CommandStatic

discover()

discover(dir): Promise<string[]>

Defined in: packages/core/src/command/CommandRunner.ts:252

Import every non-test module under a directory and register any exported command classes it finds. Returns the names that were registered.

Parameters

dir

string

Returns

Promise<string[]>

registerLazy()

registerLazy(name, thunk, aliases?): void

Defined in: packages/core/src/command/CommandRunner.ts:302

Register a command as a lazy thunk. The module is only imported if/when the command is called. Use this in web mode to avoid parsing CLI files during HTTP boot.

Parameters

name

string

thunk

CommandThunk

aliases?

string[] = []

Returns

void

Example

runner.registerLazy('cache:clear',
  () => import('@zerotal/cache/commands').then(m => m.CacheClearCommand)
);

boot()

boot(): Promise<void>

Defined in: packages/core/src/command/CommandRunner.ts:319

Register self in the container, boot the application, and register the built-in commands appropriate to the current environment.

Called by the CLI entry point (zt.ts) before CommandRunner.run.

Environment is set by zt.ts via Bun.env['APP_ENV'] BEFORE bootstrap/app.ts is dynamically imported. Application.create() reads it, so _env is already correct by the time boot() runs — no argv inspection needed here.

Returns

Promise<void>

run()

run(argv): Promise<void>

Defined in: packages/core/src/command/CommandRunner.ts:413

Parse argv, run the matched command, and exit the process with its status. Handles the built-in list and help commands. Intended for CLI use.

Parameters

argv

string[]

Returns

Promise<void>

callInProcess()

callInProcess(argv, parameters?): Promise<{ code: number; output: string; }>

Defined in: packages/core/src/command/CommandRunner.ts:467

Run a command in-process and return { code, output }. Does NOT call process.exit(). Safe to call from HTTP handlers. Output is captured via BufferWriter — nothing is written to stdout.

See: plans/boot-modes.md §6

Parameters

argv

string[]

parameters?

Record<string, string | boolean | number> = {}

Returns

Promise<{ code: number; output: string; }>