Toolbox: Runtime

The runtime property provides access to the CLI instance, allowing you to call other commands programmatically.

Accessing Runtime

execute: ({ runtime }) => {
    // runtime is the CLI instance
    const cliName = runtime.getCliName();
    const commands = runtime.getCommands();
};

Calling Other Commands

Use runtime.runCommand() to execute other commands:

cli.addCommand({
    name: "deploy",
    execute: async ({ runtime, logger }) => {
        logger.info("Building...");
        await runtime.runCommand("build", {
            argv: ["--production"],
        });

        logger.info("Deploying...");
    },
});

Passing Arguments

await runtime.runCommand("copy", {
    argv: ["file1.txt", "file2.txt"],
});

Passing Options

await runtime.runCommand("build", {
    argv: ["--production", "--output", "dist"],
});

Merging Options

await runtime.runCommand("build", {
    argv: ["--production"],
    customOption: "value",
});

Getting Return Values

const result = await runtime.runCommand("calculate");
console.log(result); // Command return value

Runtime Methods

getCliName()

Get the CLI application name:

const name = runtime.getCliName(); // "my-app"

getCommands()

Get all registered commands:

const commands = runtime.getCommands(); // Map<string, Command>
commands.forEach((command, name) => {
    console.log(`Command: ${name}`);
});

getCwd()

Get the current working directory:

const cwd = runtime.getCwd(); // "/path/to/project"

getPackageName()

Get the package name if configured:

const packageName = runtime.getPackageName(); // "my-app" | undefined

getPackageVersion()

Get the package version if configured:

const version = runtime.getPackageVersion(); // "1.0.0" | undefined

getPluginManager()

Get the plugin manager instance:

const pluginManager = runtime.getPluginManager();
// Advanced plugin management

Command Composition Examples

Build Pipeline

cli.addCommand({
    name: "ci",
    execute: async ({ runtime, logger }) => {
        logger.info("Running CI pipeline...");

        await runtime.runCommand("lint");
        await runtime.runCommand("test", { argv: ["--coverage"] });
        await runtime.runCommand("build", { argv: ["--production"] });

        logger.info("CI pipeline complete!");
    },
});

Conditional Execution

cli.addCommand({
    name: "release",
    options: [{ name: "skip-tests", type: Boolean }],
    execute: async ({ runtime, options, logger }) => {
        if (!options.skipTests) {
            logger.info("Running tests...");
            await runtime.runCommand("test");
        }

        logger.info("Building release...");
        await runtime.runCommand("build", { argv: ["--production"] });
    },
});

Nested Command Calls

cli.addCommand({
    name: "deploy",
    execute: async ({ runtime }) => {
        await runtime.runCommand("build");
    },
});

cli.addCommand({
    name: "build",
    execute: async ({ runtime }) => {
        await runtime.runCommand("compile");
        await runtime.runCommand("bundle");
    },
});

Error Handling

Errors from called commands propagate:

cli.addCommand({
    name: "deploy",
    execute: async ({ runtime, logger }) => {
        try {
            await runtime.runCommand("build");
        } catch (error) {
            logger.error("Build failed:", error);
            throw error; // Re-throw to stop deployment
        }

        await runtime.runCommand("deploy-step");
    },
});

Best Practices

Use for composition - Break complex operations into smaller commands
Handle errors - Wrap runCommand calls in try-catch when needed
Pass options explicitly - Use argv array for clarity
Avoid circular calls - Don't create command call loops
Document dependencies - Make it clear which commands depend on others

Runtime