@reliverse/rempts 1.7.1 → 1.7.3

package/README.md

@@ -2,7 +2,7 @@
 
 > @reliverse/rempts is a modern, type-safe toolkit for building delightful cli experiences. it's fast, flexible, and made for developer happiness. file-based commands keep things simple—no clutter, just clean and easy workflows. this is how cli should feel.
 
-[💬 Discord](https://discord.gg/3GawfWfAPe) — [📦 NPM](https://npmjs.com/package/@reliverse/rempts) — [🧠 Docs](https://docs.reliverse.org/reliverse/rempts) — [🌐 JSR](https://jsr.io/@reliverse/rempts) — [✨ GitHub](https://github.com/reliverse/rempts)
+[sponsor](https://github.com/sponsors/blefnk) — [discord](https://discord.gg/Pb8uKbwpsJ) — [repo](https://github.com/reliverse/rempts) — [npm](https://npmjs.com/@reliverse/rempts)
 
 ## Features
 
@@ -18,7 +18,7 @@
 - 🚨 Crash-safe (Ctrl+C, SIGINT, errors)
 - 🪄 Minimal API surface, max expressiveness
 - 🧪 Scriptable for testing, stable for production
-- 🆕 Automatic commands creation (via `dler init --cmd my-cool-cmd`)
+- 🆕 Automatic commands creation (via `dler rempts init --cmd my-cool-cmd`)
 - 🏞️ No more hacking together `inquirer`, `citty`, `commander`, `chalk`
 
 ## Installation
@@ -27,6 +27,14 @@
 bun add @reliverse/rempts
 ```
 
+**Coming soon**:
+
+```bash
+bun i -g @reliverse/dler
+dler rempts init --cmd my-cmd-1
+dler rempts init --cmds
+```
+
 ## Usage Examples
 
 - [Prompts](#prompts)
@@ -130,14 +138,14 @@ await main();
 ### Terminology
 
 - **Launcher/Router**: The main entry point for your CLI. Visit [CLI Launcher (Router)](#cli-launcher-router) section to learn more.
-- **Command/Subcommand**: A command is a function that defines the behavior of a CLI.
+- **Command**: A command is a function that defines the inner script launched by the main script where runMain() is used or by some other command.
 - **Argument**: An argument is a value that is passed to a command.
 - **Flag**: A flag is a boolean argument that is used to enable or disable a feature.
 - **Option**: An option is a named argument that is used to configure a command.
 
 #### Launcher Usage Example
 
-‼️ Go to [Usage Examples](#usage-examples) section for a more detailed example.
+**Important**: Ensure your commands don't have `await main();`, `await runMain();`, or something like that — to prevent any unexpected behavior. Only main command should have it.
 
 ```ts
 import { relinka } from "@reliverse/relinka";
@@ -156,7 +164,7 @@ const main = defineCommand({
   onCmdEnd() {
     relinka("success", "Cleanup");
   },
-  subCommands: {
+  commands: {
     build: () => import("./app/build/cmd.js").then((r) => r.default),
     deploy: () => import("./app/deploy/cmd.js").then((r) => r.default),
     debug: () => import("./app/debug/cmd.js").then((r) => r.default),
@@ -177,9 +185,9 @@ await runMain(myCommand, {
 });
 ```
 
-This flexibility allows you to easily build a rich, multi-command CLI with minimal boilerplate. The launcher even supports nested subcommands, making it simple to construct complex CLI applications.
+This flexibility allows you to easily build a rich, multi-command CLI with minimal boilerplate. The launcher even supports nested commands, making it simple to construct complex CLI applications.
 
-#### File-Based Subcommands
+#### File-Based Commands
 
 Drop a `./src/cli/app/add/index.ts` and it's live.
 
@@ -199,7 +207,7 @@ export default defineCommand({
     }),
   },
   async run({ args }) {
-    relinka("info", "Adding:", args.name);
+    relinka("log", "Adding:", args.name);
   },
 });
 ```
@@ -214,7 +222,7 @@ export default defineCommand({
 **Hint**:
 
 - Install `bun add -D @reliverse/dler`
-- Use `dler init --cmd cmd1 cmd2` to init commands for rempts launcher's automatically
+- Use `dler rempts init --cmd cmd1 cmd2` to init commands for rempts launcher's automatically
 
 ### Advanced Minimal API
 
@@ -227,7 +235,7 @@ defineCommand({
     animals: { type: "array", options: ["cat","dog"] },
   },
   async run({ args, raw }) { // or `async run(ctx)`
-    relinka("info", args.name, args.verbose, args.animals); // or `relinka("info", ctx.args.name, ...);`
+    relinka("log", args.name, args.verbose, args.animals); // or `relinka("log", ctx.args.name, ...);`
   },
 });
 ```
@@ -281,7 +289,7 @@ await runMain(defineCommand({}));
 
 ```bash
 bun add -D @reliverse/dler # or: bun i -g @reliverse/dler
-bun dler init --cmd my-cmd-1 # or: dler init my-cmd-1 my-cmd-2 --main src/mod.ts
+bun dler rempts init --cmd my-cmd-1 # or: dler rempts init my-cmd-1 my-cmd-2 --main src/mod.ts
 # * `--main` is optional, default is `./src/mod.ts`
 # * you can specify multiple commands at once
 ```
@@ -362,7 +370,7 @@ const main = defineCommand({
       ],
     });
 
-    relinka("info", "You have selected:", { name, framework });
+    relinka("log", "You have selected:", { name, framework });
   },
 });
 
@@ -388,7 +396,7 @@ import {
  * This command demonstrates the full range of launcher features along with all supported argument types:
  *
  * - Global Usage Handling: Automatically processes `--help` and `--version`.
- * - File-Based Subcommands: Scans "app" for subcommands (e.g., `init`).
+ * - File-Based Commands: Scans "app" for commands (e.g., `init`).
  * - Comprehensive Argument Parsing: Supports positional, boolean, string, number, and array arguments.
  * - Interactive Prompts: Uses built-in prompt functions for an engaging CLI experience.
  */
@@ -397,7 +405,7 @@ const mainCommand = defineCommand({
     name: "rempts",
     version: "1.6.0",
     description:
-      "An example CLI that supports file-based subcommands and all argument types.",
+      "An example CLI that supports file-based commands and all argument types.",
   },
   args: {
     // Positional arguments
@@ -440,10 +448,10 @@ const mainCommand = defineCommand({
   },
   async run({ args, raw }) {
     // Display invocation details and parsed arguments.
-    relinka("info", "Main command was invoked!");
-    relinka("info", "Parsed main-command args:", args);
-    relinka("info", "Raw argv:", raw);
-    relinka("info", "\nHelp: `rempts --help`, `rempts cmdName --help`");
+    relinka("log", "Main command was invoked!");
+    relinka("log", "Parsed main-command args:", args);
+    relinka("log", "Raw argv:", raw);
+    relinka("log", "\nHelp: `rempts --help`, `rempts cmdName --help`");
 
     // Begin interactive session with a prompt.
     await startPrompt({
@@ -467,7 +475,7 @@ const mainCommand = defineCommand({
     });
 
     // Log all gathered input details.
-    relinka("info", "You have selected:", {
+    relinka("log", "You have selected:", {
       projectName,
       framework,
       inputFile: args.inputFile,
@@ -483,7 +491,7 @@ const mainCommand = defineCommand({
 /**
  * The `runMain()` function sets up the launcher with several advanced features:
  *
- * - File-Based Subcommands: Enables scanning for subcommands within the "app" directory.
+ * - File-Based Commands: Enables scanning for commands within the "app" directory.
  * - Alias Mapping: Shorthand flags (e.g., `-v`) are mapped to their full names (e.g., `--verbose`).
  * - Strict Mode & Unknown Flag Warnings: Unknown flags are either warned about or handled via a callback.
  * - Negated Boolean Support: Allows flags to be negated (e.g., `--no-verbose`).
@@ -491,8 +499,8 @@ const mainCommand = defineCommand({
  */
 await runMain(mainCommand, {
   fileBasedCmds: {
-    enable: true, // Enables file-based subcommand detection.
-    cmdsRootPath: "app", // Directory to scan for subcommands.
+    enable: true, // Enables file-based command detection.
+    cmdsRootPath: "app", // Directory to scan for commands.
   },
   alias: {
     v: "verbose", // Maps shorthand flag -v to --verbose.
@@ -509,10 +517,10 @@ await runMain(mainCommand, {
 
 ### CLI Launcher (Router)
 
-Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'s so called "launcher" is a uniquely powerful and ergonomic CLI toolkit—one that helps you build delightful developer experiences with less code and more confidence. The launcher supports both programmatically defined subcommands and file-based routing, so you can structure your CLI however you like. It automatically detects and loads subcommands from your filesystem and provides robust usage and error handling out-of-the-box. The launcher is more than just a command runner—it's a robust, developer-friendly engine with several advanced features and thoughtful design choices:
+Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'s so called "launcher" is a uniquely powerful and ergonomic CLI toolkit—one that helps you build delightful developer experiences with less code and more confidence. The launcher supports both programmatically defined commands and file-based routing, so you can structure your CLI however you like. It automatically detects and loads commands from your filesystem and provides robust usage and error handling out-of-the-box. The launcher is more than just a command runner—it's a robust, developer-friendly engine with several advanced features and thoughtful design choices:
 
-- **File-Based & Defined Subcommands:**  
-  Use `subCommands` in your command definition or let the launcher automatically load commands from a specified directory.
+- **File-Based & Defined Commands:**  
+  Use `commands` in your command definition or let the launcher automatically load commands from a specified directory.
 
 - **Automatic Command Detection:**  
   The launcher scans your specified `cmdsRootPath` for command files matching common patterns such as:
@@ -539,20 +547,20 @@ Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'
 - **Lifecycle Hooks:**
   You can define optional lifecycle hooks in your main command:
   - `onLauncherStart` and `onLauncherEnd` (global, called once per CLI process)
-  - `onCmdStart` and `onCmdEnd` (per-subcommand, called before/after each subcommand, but NOT for the main `run()` handler)
+  - `onCmdStart` and `onCmdEnd` (per-command, called before/after each command, but NOT for the main `run()` handler)
 
   **Global Hooks:**
-  - `onLauncherStart`: Called once, before any command/subcommand/run() is executed.
-  - `onLauncherEnd`: Called once, after all command/subcommand/run() logic is finished (even if an error occurs).
+  - `onLauncherStart`: Called once, before any command/run() is executed.
+  - `onLauncherEnd`: Called once, after all command/run() logic is finished (even if an error occurs).
 
-  **Per-Subcommand Hooks:**
-  - `onCmdStart`: Called before each subcommand (not for main `run()`).
-  - `onCmdEnd`: Called after each subcommand (not for main `run()`).
+  **Per-Command Hooks:**
+  - `onCmdStart`: Called before each command (not for main `run()`).
+  - `onCmdEnd`: Called after each command (not for main `run()`).
 
   This means:
-  - If your CLI has multiple subcommands, `onCmdStart` and `onCmdEnd` will be called for each subcommand invocation, not just once for the whole CLI process.
-  - If your main command has a `run()` handler (and no subcommand is invoked), these hooks are **not** called; use the `run()` handler itself or the global hooks for such logic.
-  - This allows you to perform setup/teardown logic specific to each subcommand execution.
+  - If your CLI has multiple commands, `onCmdStart` and `onCmdEnd` will be called for each command invocation, not just once for the whole CLI process.
+  - If your main command has a `run()` handler (and no command is invoked), these hooks are **not** called; use the `run()` handler itself or the global hooks for such logic.
+  - This allows you to perform setup/teardown logic specific to each command execution.
   - If you want logic to run only once for the entire CLI process, use `onLauncherStart` and `onLauncherEnd`.
 
   **Example:**
@@ -561,27 +569,29 @@ Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'
   const main = defineCommand({
     onLauncherStart() { relinka('info', 'Global setup (once per process)'); },
     onLauncherEnd() { relinka('info', 'Global cleanup (once per process)'); },
-    onCmdStart() { relinka('info', 'Setup for each subcommand'); },
-    onCmdEnd() { relinka('info', 'Cleanup for each subcommand'); },
-    subCommands: { ... },
-    run() { relinka('info', 'Main run handler (no subcommand)'); },
+    onCmdStart() { relinka('info', 'Setup for each command'); },
+    onCmdEnd() { relinka('info', 'Cleanup for each command'); },
+    commands: { ... },
+    run() { relinka('info', 'Main run handler (no command)'); },
   });
   // onLauncherStart/onLauncherEnd are called once per process
-  // onCmdStart/onCmdEnd are called for every subcommand (not for main run())
+  // onCmdStart/onCmdEnd are called for every command (not for main run())
   // If you want per-run() logic, use the run() handler or global hooks
   ```
 
-  > **Note:** The legacy `setup` and `cleanup` names are still supported as aliases for per-command hooks, but will be removed in a future major version. Prefer `onCmdStart` and `onCmdEnd` going forward.
+- **Deprecation Notice**
+  - The legacy `setup` and `cleanup` names are still supported as aliases for per-command hooks, but will be removed in a future major version. Prefer `onCmdStart` and `onCmdEnd` going forward.
+  - The `subCommands` property is deprecated as well. Please use `commands` instead. `subCommands` will be removed in a future major version.
 
 - **Dynamic Usage Examples:**
-  - The launcher inspects your available subcommands and their argument definitions, then prints a plausible example CLI invocation for a random subcommand directly in the help output. This helps users understand real-world usage at a glance.
+  - The launcher inspects your available commands and their argument definitions, then prints a plausible example CLI invocation for a random command directly in the help output. This helps users understand real-world usage at a glance.
 
-- **File-Based & Programmatic Subcommands:**
-  - Both file-based and object subcommands are fully supported. The launcher can introspect their argument definitions and metadata for help, usage, and validation.
-  - File-based subcommands are auto-discovered from your filesystem, while programmatic subcommands can be defined inline in your main command.
+- **File-Based & Programmatic Commands:**
+  - Both file-based and object commands are fully supported. The launcher can introspect their argument definitions and metadata for help, usage, and validation.
+  - File-based commands are auto-discovered from your filesystem, while programmatic commands can be defined inline in your main command.
 
 - **Context-Aware Help Output:**
-  - The help/usage output adapts to your CLI's structure, showing available subcommands, their aliases, argument details, and even dynamic usage examples. It also displays global options and context-specific error messages.
+  - The help/usage output adapts to your CLI's structure, showing available commands, their aliases, argument details, and even dynamic usage examples. It also displays global options and context-specific error messages.
 
 - **Error Handling:**
   - The launcher provides clear, actionable error messages for missing required arguments, invalid types, unknown commands, and import errors. It always shows relevant usage information to help users recover quickly.
@@ -598,6 +608,92 @@ Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'
 - **Prompt-First, Modern UX:**
   - The launcher integrates tightly with the prompt engine, so you can build interactive, delightful CLIs with minimal effort.
 
+### Launcher Programmatic Execution
+
+For larger CLIs or when you want to programmatically run commands (e.g.: [prompt demo](./example/prompts/mod.ts), tests, etc), you can organize your commands in a `cmds.ts` file and use the `runCmd` utility.
+
+**Pro Tips & Best Practices**:
+
+- Install `dler` globally and run `dler rempts init --cmds` to generate a `src/app/cmds.ts` (custom path is supported) file in your project.
+- You can use any name for the `cmds.ts` file and store it anywhere, but `src/app/cmds.ts` is a good convention you can follow.
+- Use the async function pattern for lazy loading if you have many commands or care about startup performance.
+- Use eager loading (const) for small CLIs or demos where simplicity is preferred.
+
+**Lazy Loading (Recommended for Most CLIs)**:
+
+```ts
+// example/launcher/app/cmds.ts
+
+export async function getCmdHooks() {
+  return (await import("./hooks/cmd.js")).default;
+}
+
+export async function getCmdFoo() {
+  return (await import("./foo/cmd.js")).default;
+}
+
+// ...more commands
+```
+
+Usage:
+
+```ts
+// example/prompts/mod.ts
+
+import { getCmdHooks } from "@/launcher/app/cmds.js";
+import { runCmd } from "@reliverse/rempts";
+
+await runCmd(await getCmdHooks(), ["--flag"]);
+// OR:
+// const hooksCmd = await getCmdHooks();
+// await runCmd(hooksCmd, ["--flag"]);
+```
+
+**Alternative: Eager Loading (All Commands Loaded at Startup)**:
+
+```ts
+// example/launcher/app/cmds.ts
+export const hooksCmd = (await import("./hooks/cmd.js")).default;
+export const fooCmd = (await import("./foo/cmd.js")).default;
+// ...more commands
+```
+
+Usage:
+
+```ts
+import { hooksCmd } from "./cmds.js";
+import { runCmd } from "@reliverse/rempts";
+
+await runCmd(hooksCmd, ["--flag"]);
+```
+
+**Programmatic Command Execution with `runCmd`**:
+
+The `runCmd` utility lets you run a command's `run()` handler with parsed arguments, outside of the full launcher context. This is useful for demos, tests, or custom flows:
+
+```ts
+import { runCmd } from "@reliverse/rempts";
+import { hooksCmd } from "./cmds.js";
+
+await runCmd(hooksCmd, ["--flag"]); // argv as array of strings
+```
+
+Or with lazy loading:
+
+```ts
+const hooksCmd = await getCmdHooks();
+await runCmd(hooksCmd, ["--flag"]);
+```
+
+**Note:** `runCmd` only runs the command's `run()` handler and does not handle subcommands, file-based commands, or global hooks. For full CLI behavior, use `runMain`.
+
+**Performance Note:**
+
+- Eager loading (`const`) loads all commands at startup, which may impact performance for large CLIs.
+- Lazy loading (`async function`) loads each command only when needed, improving startup time and memory usage.
+
+Choose the pattern that best fits your CLI's size and usage!
+
 ## Contributing
 
 Bug report? Prompt idea? Want to build the best DX possible?

package/bin/components/launcher/deprecated/launcher-mod.ts.txt

@@ -27,7 +27,7 @@ export async function runMain<T extends ArgsDef = ArgsDef>(
       if (!meta?.version) {
         throw new CLIError("No version specified", "E_NO_VERSION");
       }
-      relinka("info", meta.version);
+      relinka("log", meta.version);
     } else {
       await runCommand(cmd, { rawArgs });
     }

package/bin/components/launcher/deprecated/usage.ts.txt

@@ -12,7 +12,7 @@ export async function showUsage<T extends ArgsDef = ArgsDef>(
 ) {
   try {
     // biome-ignore lint/style/useTemplate: <explanation>
-    relinka("info", (await renderUsage(cmd, parent)) + "\n");
+    relinka("log", (await renderUsage(cmd, parent)) + "\n");
   } catch (error) {
     relinka("error", String(error));
   }

package/bin/components/launcher/launcher-mod.d.ts

@@ -44,42 +44,50 @@ type CommandMeta = {
  * 2) A lazy import function returning a Promise that resolves to
  *    { default: Command<any> } or directly to a Command instance.
  */
-type SubCommandSpec = string | (() => Promise<{
+type CommandSpec = string | (() => Promise<{
     default: Command<any>;
 } | Command<any>>);
-export type SubCommandsMap = Record<string, SubCommandSpec>;
+export type CommandsMap = Record<string, CommandSpec>;
 type CommandContext<ARGS> = {
     args: ARGS;
     raw: string[];
 };
 type CommandRun<ARGS> = (ctx: CommandContext<ARGS>) => void | Promise<void>;
+type CommandHook<ARGS> = (ctx: CommandContext<ARGS>) => void | Promise<void>;
 type DefineCommandOptions<A extends ArgDefinitions = EmptyArgs> = {
     meta?: CommandMeta;
     args?: A;
     run?: CommandRun<InferArgTypes<A>>;
-    subCommands?: SubCommandsMap;
     /**
-     * Called before the command or subcommand runs
+     * Object subcommands for this command.
      */
-    onCmdStart?: () => void | Promise<void>;
+    commands?: CommandsMap;
     /**
-     * Called after the command or subcommand finishes
+     * @deprecated Use `commands` instead. Will be removed in a future major version.
      */
-    onCmdEnd?: () => void | Promise<void>;
+    subCommands?: CommandsMap;
+    /**
+     * Called before the command runs. Receives `{ args, raw }` (parsed args and raw argv).
+     */
+    onCmdStart?: CommandHook<InferArgTypes<A>>;
+    /**
+     * Called after the command finishes. Receives `{ args, raw }` (parsed args and raw argv).
+     */
+    onCmdEnd?: CommandHook<InferArgTypes<A>>;
     /**
      * @deprecated Use onCmdStart instead
      */
-    setup?: () => void | Promise<void>;
+    setup?: CommandHook<InferArgTypes<A>>;
     /**
      * @deprecated Use onCmdEnd instead
      */
-    cleanup?: () => void | Promise<void>;
+    cleanup?: CommandHook<InferArgTypes<A>>;
     /**
-     * Called once per CLI process, before any command/subcommand/run() is executed
+     * Called once per CLI process, before any command/run() is executed
      */
     onLauncherStart?: () => void | Promise<void>;
     /**
-     * Called once per CLI process, after all command/subcommand/run() logic is finished
+     * Called once per CLI process, after all command/run() logic is finished
      */
     onLauncherEnd?: () => void | Promise<void>;
 };
@@ -87,29 +95,36 @@ export type Command<A extends ArgDefinitions = EmptyArgs> = {
     meta?: CommandMeta;
     args: A;
     run?: CommandRun<InferArgTypes<A>>;
-    subCommands?: SubCommandsMap;
     /**
-     * Called before the command or subcommand runs
+     * Object subcommands for this command.
+     */
+    commands?: CommandsMap;
+    /**
+     * @deprecated Use `commands` instead. Will be removed in a future major version.
      */
-    onCmdStart?: () => void | Promise<void>;
+    subCommands?: CommandsMap;
     /**
-     * Called after the command or subcommand finishes
+     * Called before the command runs. Receives `{ args, raw }` (parsed args and raw argv).
      */
-    onCmdEnd?: () => void | Promise<void>;
+    onCmdStart?: CommandHook<InferArgTypes<A>>;
+    /**
+     * Called after the command finishes. Receives `{ args, raw }` (parsed args and raw argv).
+     */
+    onCmdEnd?: CommandHook<InferArgTypes<A>>;
     /**
      * @deprecated Use onCmdStart instead
      */
-    setup?: () => void | Promise<void>;
+    setup?: CommandHook<InferArgTypes<A>>;
     /**
      * @deprecated Use onCmdEnd instead
      */
-    cleanup?: () => void | Promise<void>;
+    cleanup?: CommandHook<InferArgTypes<A>>;
     /**
-     * Called once per CLI process, before any command/subcommand/run() is executed
+     * Called once per CLI process, before any command/run() is executed
      */
     onLauncherStart?: () => void | Promise<void>;
     /**
-     * Called once per CLI process, after all command/subcommand/run() logic is finished
+     * Called once per CLI process, after all command/run() logic is finished
      */
     onLauncherEnd?: () => void | Promise<void>;
 };
@@ -152,11 +167,11 @@ export declare function showUsage<A extends ArgDefinitions>(command: Command<A>,
 /**
  * Primary entry point to run a command. This function supports:
  *
- * - File-based Subcommands: scanning for subcommands within a given commands root.
- * - SubCommands defined within the command object.
+ * - File-based Commands: scanning for commands within a given commands root.
+ * - Commands defined within the command object.
  * - Standard flags like --help, --version, and --debug.
  *
- * This function passes along remaining arguments to subcommand runners to ensure
+ * This function passes along remaining arguments to command runners to ensure
  * consistent parsing.
  */
 export declare function runMain<A extends ArgDefinitions = EmptyArgs>(command: Command<A>, parserOptions?: ReliArgParserOptions & {
@@ -174,4 +189,14 @@ export declare function runMain<A extends ArgDefinitions = EmptyArgs>(command: C
  * precise default value validation (e.g., `options: ["a", "b"] as const`).
  */
 export declare function defineArgs<A extends ArgDefinitions>(args: A & ValidateArrayDefaults<A>): A;
+/**
+ * Programmatically run a command's run() handler with parsed arguments.
+ * Does not handle subcommands, file-based commands, or global hooks.
+ * Suitable for use in demos, tests, or programmatic invocation.
+ *
+ * @param command The command definition (from defineCommand)
+ * @param argv The argv array to parse (default: [])
+ * @param parserOptions Optional reliArgParser options
+ */
+export declare function runCmd<A extends ArgDefinitions = EmptyArgs>(command: Command<A>, argv?: string[], parserOptions?: ReliArgParserOptions): Promise<void>;
 export {};

package/bin/components/launcher/launcher-mod.js

@@ -50,7 +50,7 @@ function buildExampleArgs(args) {
 const isDebugMode = process.argv.includes("--debug");
 function debugLog(...args) {
   if (isDebugMode) {
-    relinka("info", "[DEBUG]", ...args);
+    relinka("log", "[DEBUG]", ...args);
   }
 }
 function isFlag(str) {
@@ -61,11 +61,15 @@ export function defineCommand(options) {
   const onCmdEnd = options.onCmdEnd || options.cleanup;
   const onLauncherStart = options.onLauncherStart;
   const onLauncherEnd = options.onLauncherEnd;
-  return {
+  let commands = options.commands;
+  if (!commands) {
+    commands = options.subCommands;
+  }
+  const cmdObj = {
     meta: options.meta,
     args: options.args || {},
     run: options.run,
-    subCommands: options.subCommands,
+    commands,
     onCmdStart,
     onCmdEnd,
     onLauncherStart,
@@ -74,6 +78,14 @@ export function defineCommand(options) {
     setup: onCmdStart,
     cleanup: onCmdEnd
   };
+  Object.defineProperty(cmdObj, "subCommands", {
+    get() {
+      return this.commands;
+    },
+    enumerable: false,
+    configurable: true
+  });
+  return cmdObj;
 }
 let _cachedDefaultCliName;
 let _cachedDefaultCliVersion;
@@ -97,7 +109,7 @@ export async function showUsage(command, parserOptions = {}, displayNotFoundMess
   const { name: fallbackName, version: fallbackVersion } = await getDefaultCliNameAndVersion();
   const cliName = command.meta?.name || fallbackName;
   const cliVersion = command.meta?.version || fallbackVersion;
-  relinka("info", `${cliName}${cliVersion ? ` v${cliVersion}` : ""}`);
+  relinka("log", `${cliName}${cliVersion ? ` v${cliVersion}` : ""}`);
   if (parserOptions.metaSettings?.showDescriptionOnMain) {
     let description = command.meta?.description;
     if (!description) {
@@ -173,8 +185,9 @@ export async function showUsage(command, parserOptions = {}, displayNotFoundMess
   } else {
     const subCommandNames = [];
     const subCommandDefs = [];
-    if (command.subCommands) {
-      for (const [name, spec] of Object.entries(command.subCommands)) {
+    const objectCommands = command.commands;
+    if (objectCommands) {
+      for (const [name, spec] of Object.entries(objectCommands)) {
         try {
           const cmd = await loadSubCommand(spec);
           if (!cmd?.meta?.hidden) {
@@ -183,7 +196,7 @@ export async function showUsage(command, parserOptions = {}, displayNotFoundMess
             subCommandDefs.push({ name, def: cmd });
           }
         } catch (err) {
-          debugLog(`Error loading subcommand ${name}:`, err);
+          debugLog(`Error loading command ${name}:`, err);
         }
       }
     }
@@ -240,7 +253,7 @@ export async function runMain(command, parserOptions = {}) {
   if (typeof command.onLauncherStart === "function")
     await command.onLauncherStart();
   try {
-    if (!parserOptions.fileBasedCmds && !command.subCommands) {
+    if (!parserOptions.fileBasedCmds && !command.commands) {
       let callerDir = process.cwd();
       let callerFile;
       try {
@@ -289,7 +302,7 @@ This can cause recursion or unexpected behavior.`
     }
     const rawArgv = process.argv.slice(2);
     const autoExit = parserOptions.autoExit !== false;
-    if (!(parserOptions.fileBasedCmds?.enable || command.subCommands && Object.keys(command.subCommands).length > 0 || command.run)) {
+    if (!(parserOptions.fileBasedCmds?.enable || command.commands && Object.keys(command.commands).length > 0 || command.run)) {
       relinka(
         "error",
         "Invalid CLI configuration: No file-based commands, subCommands, or run() handler are defined. This CLI will not do anything.\n\u2502   To fix: add file-based commands (./app), or provide at least one subCommand or a run() handler."
@@ -310,7 +323,7 @@ This can cause recursion or unexpected behavior.`
     if (checkVersion(rawArgv)) {
       if (command.meta?.name) {
         relinka(
-          "info",
+          "log",
           `${command.meta?.name} ${command.meta?.version ? `v${command.meta?.version}` : ""}`
         );
       }
@@ -321,14 +334,17 @@ This can cause recursion or unexpected behavior.`
     if (fileBasedEnabled && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
       const [subName, ...subCmdArgv] = rawArgv;
       try {
+        const ctx = getParsedContext(command, rawArgv, parserOptions);
         if (typeof command.onCmdStart === "function")
-          await command.onCmdStart();
+          await command.onCmdStart(ctx);
         await runFileBasedSubCmd(
           subName,
           subCmdArgv,
           parserOptions.fileBasedCmds,
           parserOptions,
-          command.onCmdEnd
+          command.onCmdEnd ? async (_subCtx) => {
+            await command.onCmdEnd?.(ctx);
+          } : void 0
         );
         if (autoExit) process.exit(0);
         return;
@@ -338,10 +354,10 @@ This can cause recursion or unexpected behavior.`
         throw err;
       }
     }
-    if (!fileBasedEnabled && command.subCommands && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
+    if (!fileBasedEnabled && command.commands && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
       const [maybeSub, ...subCmdArgv] = rawArgv;
       let subSpec;
-      for (const [key, spec] of Object.entries(command.subCommands)) {
+      for (const [key, spec] of Object.entries(command.commands)) {
         if (key === maybeSub) {
           subSpec = spec;
           break;
@@ -353,18 +369,21 @@ This can cause recursion or unexpected behavior.`
             break;
           }
         } catch (err) {
-          debugLog(`Error checking alias for subcommand ${key}:`, err);
+          debugLog(`Error checking alias for command ${key}:`, err);
         }
       }
       if (subSpec) {
         try {
+          const ctx = getParsedContext(command, rawArgv, parserOptions);
           if (typeof command.onCmdStart === "function")
-            await command.onCmdStart();
+            await command.onCmdStart(ctx);
           await runSubCommand(
             subSpec,
             subCmdArgv,
             parserOptions,
-            command.onCmdEnd
+            command.onCmdEnd ? async (_subCtx) => {
+              await command.onCmdEnd?.(ctx);
+            } : void 0
           );
           if (autoExit) process.exit(0);
           return;
@@ -461,20 +480,32 @@ Info for this CLI's developer: No valid command directory found, expected: ${exp
     );
   }
   try {
-    await runCommandWithArgs(subCommand, argv, parserOptions);
+    const subCtx = await runCommandWithArgs(
+      subCommand,
+      argv,
+      parserOptions,
+      true
+    );
+    if (typeof parentFinish === "function" && subCtx)
+      await parentFinish(subCtx);
   } finally {
-    if (typeof parentFinish === "function") await parentFinish();
   }
 }
 async function runSubCommand(spec, argv, parserOptions, parentFinish) {
   const subCommand = await loadSubCommand(spec);
   try {
-    await runCommandWithArgs(subCommand, argv, parserOptions);
+    const subCtx = await runCommandWithArgs(
+      subCommand,
+      argv,
+      parserOptions,
+      true
+    );
+    if (typeof parentFinish === "function" && subCtx)
+      await parentFinish(subCtx);
   } finally {
-    if (typeof parentFinish === "function") await parentFinish();
   }
 }
-async function runCommandWithArgs(command, argv, parserOptions) {
+async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
   const autoExit = parserOptions.autoExit !== false;
   const booleanKeys = Object.keys(command.args || {}).filter(
     (k) => command.args[k].type === "boolean"
@@ -556,7 +587,7 @@ async function runCommandWithArgs(command, argv, parserOptions) {
     if (command.run) {
       await command.run(ctx);
     } else {
-      const isDispatcher = parserOptions.fileBasedCmds?.enable || command.subCommands && Object.keys(command.subCommands).length > 0;
+      const isDispatcher = parserOptions.fileBasedCmds?.enable || command.commands && Object.keys(command.commands).length > 0;
       const noSubcommandArgInCurrentCall = !argv.some((arg) => !isFlag(arg));
       if (isDispatcher && noSubcommandArgInCurrentCall) {
         relinka("warn", "Please specify a command");
@@ -580,6 +611,8 @@ ${String(err)}`);
     if (autoExit) process.exit(1);
     else throw err;
   }
+  if (returnCtx) return ctx;
+  return void 0;
 }
 function castArgValue(def, rawVal, argName) {
   if (rawVal == null) {
@@ -624,3 +657,118 @@ function renderPositional(args) {
 export function defineArgs(args) {
   return args;
 }
+export async function runCmd(command, argv = [], parserOptions = {}) {
+  const booleanKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args[k].type === "boolean"
+  );
+  const defaultMap = {};
+  for (const [argKey, def] of Object.entries(command.args || {})) {
+    if (def.default !== void 0) {
+      if (def.type === "array" && typeof def.default === "string") {
+        defaultMap[argKey] = [def.default];
+      } else {
+        defaultMap[argKey] = def.default;
+      }
+    }
+  }
+  const mergedParserOptions = {
+    ...parserOptions,
+    boolean: [...parserOptions.boolean || [], ...booleanKeys],
+    defaults: { ...defaultMap, ...parserOptions.defaults || {} }
+  };
+  const parsed = reliArgParser(argv, mergedParserOptions);
+  debugLog("Parsed arguments (runCmd):", parsed);
+  const finalArgs = {};
+  const positionalKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args[k].type === "positional"
+  );
+  const leftoverPositionals = [...parsed._ || []];
+  for (let i = 0; i < positionalKeys.length; i++) {
+    const key = positionalKeys[i];
+    const def = command.args?.[key];
+    const val = leftoverPositionals[i];
+    if (val == null && def.required) {
+      throw new Error(`Missing required positional argument: <${key}>`);
+    }
+    finalArgs[key] = val != null ? castArgValue(def, val, key) : def.default;
+  }
+  const otherKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args[k].type !== "positional"
+  );
+  for (const key of otherKeys) {
+    const def = command.args?.[key];
+    let rawVal = parsed[key];
+    if (def.type === "array" && rawVal !== void 0 && !Array.isArray(rawVal)) {
+      rawVal = [rawVal];
+    }
+    const valueOrDefault = rawVal ?? defaultMap[key];
+    if (valueOrDefault == null && def.required) {
+      throw new Error(`Missing required argument: --${key}`);
+    }
+    finalArgs[key] = castArgValue(def, rawVal, key);
+    if (def.type === "array" && def.options && finalArgs[key]) {
+      const values = finalArgs[key];
+      const invalidOptions = values.filter(
+        (v) => def.options && !def.options.includes(v)
+      );
+      if (invalidOptions.length > 0) {
+        throw new Error(
+          `Invalid choice(s) for --${key}: ${invalidOptions.join(", ")}. Allowed options: ${def.options.join(", ")}`
+        );
+      }
+    }
+  }
+  const ctx = {
+    args: finalArgs,
+    raw: argv
+  };
+  if (typeof command.run === "function") {
+    await command.run(ctx);
+  } else {
+    throw new Error("Command has no run() handler.");
+  }
+}
+function getParsedContext(command, argv, parserOptions) {
+  const booleanKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args[k].type === "boolean"
+  );
+  const defaultMap = {};
+  for (const [argKey, def] of Object.entries(command.args || {})) {
+    if (def.default !== void 0) {
+      if (def.type === "array" && typeof def.default === "string") {
+        defaultMap[argKey] = [def.default];
+      } else {
+        defaultMap[argKey] = def.default;
+      }
+    }
+  }
+  const mergedParserOptions = {
+    ...parserOptions,
+    boolean: [...parserOptions.boolean || [], ...booleanKeys],
+    defaults: { ...defaultMap, ...parserOptions.defaults || {} }
+  };
+  const parsed = reliArgParser(argv, mergedParserOptions);
+  const finalArgs = {};
+  const positionalKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args[k].type === "positional"
+  );
+  const leftoverPositionals = [...parsed._ || []];
+  for (let i = 0; i < positionalKeys.length; i++) {
+    const key = positionalKeys[i];
+    const def = command.args?.[key];
+    const val = leftoverPositionals[i];
+    finalArgs[key] = val != null ? castArgValue(def, val, key) : def.default;
+  }
+  const otherKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args[k].type !== "positional"
+  );
+  for (const key of otherKeys) {
+    const def = command.args?.[key];
+    let rawVal = parsed[key];
+    if (def.type === "array" && rawVal !== void 0 && !Array.isArray(rawVal)) {
+      rawVal = [rawVal];
+    }
+    finalArgs[key] = castArgValue(def, rawVal, key);
+  }
+  return { args: finalArgs, raw: argv };
+}

package/bin/components/msg-fmt/messages.js

@@ -21,7 +21,10 @@ export const symbols = {
   step_active: u("\u25C6", "\u2666"),
   step_error: u("\u{1F5F4}", "x"),
   info: u("\u2139", "i"),
-  success: u("\u2705", "\u2713")
+  log: u("\u2502", "|"),
+  success: u("\u2705", "\u2713"),
+  warn: u("\u26A0", "!"),
+  error: u("\u274C", "x")
 };
 function wrapThenStyle(input, wrap, typographyName, colorName, variantName, borderColor) {
   if (!input) return "";
@@ -309,8 +312,8 @@ export function msgUndoAll() {
 }
 export function printLineBar(text, indent = 2) {
   if (text === "") {
-    relinka("info", re.dim("\u2502"));
+    relinka("log", re.dim("\u2502"));
   } else {
-    relinka("info", `${re.dim("\u2502")}${" ".repeat(indent)}${text}`);
+    relinka("log", `${re.dim("\u2502")}${" ".repeat(indent)}${text}`);
   }
 }

package/bin/components/select/multiselect-prompt.js

@@ -86,7 +86,7 @@ function renderPromptUI(params) {
     uiLineCount++;
   }
   if (debug) {
-    relinka("info", "", { optionsCount: options.length });
+    relinka("log", "", { optionsCount: options.length });
   }
   return uiLineCount;
 }

package/bin/components/select/select-prompt.js

@@ -104,7 +104,7 @@ async function renderPromptUI(params) {
     uiLineCount++;
   }
   if (debug) {
-    relinka("info", "", { optionsCount: options.length });
+    relinka("log", "", { optionsCount: options.length });
   }
   return uiLineCount;
 }

package/bin/components/select/toggle-prompt.js

@@ -59,7 +59,7 @@ function renderTogglePrompt(params) {
   msg({ type: "M_NULL", title: displayString });
   uiLineCount++;
   if (debug) {
-    relinka("info", "", {
+    relinka("log", "", {
       selectedIndex,
       displayOptions: options
     });

package/bin/components/st-end/start.js

@@ -50,9 +50,9 @@ export async function startPrompt({
   }
   if (clearConsole) {
     relinka("clear", "");
-    relinka("info", "");
+    relinka("log", "");
   } else {
-    relinka("info", "");
+    relinka("log", "");
   }
   msg({
     type: "M_START",

package/bin/components/visual/ascii-art/ascii-art.js

@@ -9,5 +9,5 @@ export async function createAsciiArt({
     relinka("clear", "");
   }
   const asciiArt = figlet.textSync(message, { font });
-  relinka("info", asciiArt);
+  relinka("log", asciiArt);
 }

package/bin/mod.d.ts

@@ -4,7 +4,7 @@ export { startEditor } from "./components/editor/editor-mod.js";
 export { mainSymbols, fallbackSymbols, } from "./components/figures/figures-mod.js";
 export { confirmPrompt } from "./components/input/confirm-prompt.js";
 export { inputPrompt } from "./components/input/input-prompt.js";
-export type { ArgDefinition, ArgDefinitions, SubCommandsMap, Command, InferArgTypes, FileBasedCmdsOptions, } from "./components/launcher/launcher-mod.js";
+export type { ArgDefinition, ArgDefinitions, CommandsMap, Command, InferArgTypes, FileBasedCmdsOptions, } from "./components/launcher/launcher-mod.js";
 export { defineCommand, defineArgs, showUsage, runMain, } from "./components/launcher/launcher-mod.js";
 export { toBaseColor, toSolidColor } from "./components/msg-fmt/colors.js";
 export { relinkaByRemptsDeprecated, relinkaAsyncByRemptsDeprecated, throwError, } from "./components/msg-fmt/logger.js";

package/bin/types.d.ts

@@ -241,7 +241,7 @@ export type RenderParams = {
 /**
  * Known symbol names that will have IntelliSense support
  */
-export type SymbolName = "pointer" | "start" | "middle" | "end" | "line" | "corner_top_right" | "step_active" | "step_error" | "info" | "success";
+export type SymbolName = "pointer" | "start" | "middle" | "end" | "line" | "corner_top_right" | "step_active" | "step_error" | "log" | "success" | "info" | "warn" | "error";
 export type Symbols = Record<SymbolName, string>;
 export type FmtMsgOptions = {
     type: MsgType;

package/bin/utils/prompt-end.js

@@ -21,14 +21,14 @@ export async function completePrompt(prompt, isCtrlC, _endTitle = "", _endTitleC
   return value ?? false;
 }
 export function renderEndLine() {
-  const lineLength = getExactTerminalWidth() - 2;
-  relinka("info", re.dim(symbols.middle));
-  relinka("info", re.dim(`${symbols.end}${symbols.line.repeat(lineLength)}\u22B1`));
-  relinka("info", "");
+  const lineLength = getExactTerminalWidth() - 6;
+  relinka("null", re.dim(symbols.middle));
+  relinka("null", re.dim(`${symbols.end}${symbols.line.repeat(lineLength)}\u22B1`));
+  relinka("null", "");
 }
 export function renderEndLineInput() {
-  const lineLength = getExactTerminalWidth() - 2;
-  relinka("info", "");
-  relinka("info", re.dim(`${symbols.end}${symbols.line.repeat(lineLength)}\u22B1`));
-  relinka("info", "");
+  const lineLength = getExactTerminalWidth() - 6;
+  relinka("null", "");
+  relinka("null", re.dim(`${symbols.end}${symbols.line.repeat(lineLength)}\u22B1`));
+  relinka("null", "");
 }

package/package.json

@@ -2,8 +2,8 @@
   "dependencies": {
     "@figliolia/chalk-animation": "^1.0.4",
     "@reliverse/reliarg": "^1.0.3",
-    "@reliverse/relico": "^1.1.1",
-    "@reliverse/relinka": "^1.4.3",
+    "@reliverse/relico": "^1.1.2",
+    "@reliverse/relinka": "^1.4.5",
     "@reliverse/runtime": "^1.0.3",
     "ansi-escapes": "^7.0.0",
     "c12": "^3.0.3",
@@ -28,7 +28,7 @@
   "license": "MIT",
   "name": "@reliverse/rempts",
   "type": "module",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "author": "reliverse",
   "bugs": {
     "email": "blefnk@gmail.com",
@@ -58,7 +58,7 @@
     "eslint-plugin-no-relative-import-paths": "^1.6.1",
     "eslint-plugin-perfectionist": "^4.13.0",
     "jiti": "^2.4.2",
-    "knip": "^5.55.1",
+    "knip": "^5.56.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.32.1",
     "vitest": "^3.1.3"