@karmaniverous/get-dotenv 5.0.0 → 5.1.0

package/dist/cliHost.d.ts

@@ -1,5 +1,13 @@
-import { ZodType } from 'zod';
 import { Command } from 'commander';
+import { ZodType } from 'zod';
+
+/**
+ * Scripts table shape (configurable shell type).
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
+    cmd: string;
+    shell?: TShell;
+}>;
 
 /**
  * A minimal representation of an environment key/value mapping.
@@ -95,6 +103,76 @@ interface GetDotenvOptions {
     useConfigLoader?: boolean;
 }
 
+type Scripts = Record<string, string | {
+    cmd: string;
+    shell?: string | boolean;
+}>;
+/**
+ * Options passed programmatically to `getDotenvCli`.
+ */
+interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
+    /**
+     * Logs CLI internals when true.
+     */
+    debug?: boolean;
+    /**
+     * When true, capture child stdout/stderr and re-emit after completion.
+     * Useful for tests/CI. Default behavior is streaming via stdio: 'inherit'.
+     */
+    capture?: boolean;
+    /**
+     * A delimited string of paths to dotenv files.
+     */
+    paths?: string;
+    /**
+     * A delimiter string with which to split `paths`. Only used if
+     * `pathsDelimiterPattern` is not provided.
+     */
+    pathsDelimiter?: string;
+    /**
+     * A regular expression pattern with which to split `paths`. Supersedes
+     * `pathsDelimiter`.
+     */
+    pathsDelimiterPattern?: string;
+    /**
+     * Scripts that can be executed from the CLI, either individually or via the batch subcommand.
+     */
+    scripts?: Scripts;
+    /**
+     * Determines how commands and scripts are executed. If `false` or
+     * `undefined`, commands are executed as plain Javascript using the default
+     * execa parser. If `true`, commands are executed using the default OS shell
+     * parser. Otherwise the user may provide a specific shell string (e.g.
+     * `/bin/bash`)
+     */
+    shell?: string | boolean;
+    /**
+     * A delimited string of key-value pairs declaratively specifying variables &
+     * values to be loaded in addition to any dotenv files.
+     */
+    vars?: string;
+    /**
+     * A string with which to split keys from values in `vars`. Only used if
+     * `varsDelimiterPattern` is not provided.
+     */
+    varsAssignor?: string;
+    /**
+     * A regular expression pattern with which to split variable names from values
+     * in `vars`. Supersedes `varsAssignor`.
+     */
+    varsAssignorPattern?: string;
+    /**
+     * A string with which to split `vars` into key-value pairs. Only used if
+     * `varsDelimiterPattern` is not provided.
+     */
+    varsDelimiter?: string;
+    /**
+     * A regular expression pattern with which to split `vars` into key-value
+     * pairs. Supersedes `varsDelimiter`.
+     */
+    varsDelimiterPattern?: string;
+}
+
 /** * Per-invocation context shared with plugins and actions. */
 type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
     optionsResolved: TOptions;
@@ -102,6 +180,7 @@ type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
     plugins?: Record<string, unknown>;
     pluginConfigs?: Record<string, unknown>;
 };
+declare const HELP_HEADER_SYMBOL: unique symbol;
 /**
  * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
  *
@@ -114,10 +193,13 @@ type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
  * NOTE: This host is additive and does not alter the legacy CLI.
  */
 declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
+    #private;
     /** Registered top-level plugins (composition happens via .use()) */
     private _plugins;
     /** One-time installation guard */
     private _installed;
+    /** Optional header line to prepend in help output */
+    private [HELP_HEADER_SYMBOL];
     constructor(alias?: string);
     /**
      * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
@@ -127,9 +209,33 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
      * Retrieve the current invocation context (if any).
      */
     getCtx(): GetDotenvCliCtx<TOptions> | undefined;
+    /**
+     * Retrieve the merged root CLI options bag (if set by passOptions()).
+     * Downstream-safe: no generics required.
+     */
+    getOptions(): GetDotenvCliOptions | undefined;
+    /** Internal: set the merged root options bag for this run. */
+    _setOptionsBag(bag: GetDotenvCliOptions): void;
     /**   * Convenience helper to create a namespaced subcommand.
      */
     ns(name: string): Command;
+    /**
+     * Tag options added during the provided callback as 'app' for grouped help.
+     * Allows downstream apps to demarcate their root-level options.
+     */
+    tagAppOptions<T>(fn: (root: Command) => T): T;
+    /**
+     * Branding helper: set CLI name/description/version and optional help header.
+     * If version is omitted and importMetaUrl is provided, attempts to read the
+     * nearest package.json version (best-effort; non-fatal on failure).
+     */
+    brand(args: {
+        name?: string;
+        description?: string;
+        version?: string;
+        importMetaUrl?: string;
+        helpHeader?: string;
+    }): Promise<this>;
     /**
      * Register a plugin for installation (parent level).
      * Installation occurs on first resolveAndLoad() (or explicit install()).
@@ -187,5 +293,11 @@ type DefineSpec = Omit<GetDotenvCliPlugin, 'children' | 'use'> & {
  */
 declare const definePlugin: (spec: DefineSpec) => GetDotenvCliPlugin;
 
-export { GetDotenvCli, definePlugin };
-export type { DefineSpec, GetDotenvCliPlugin };
+/**
+ * Helper to retrieve the merged root options bag from any action handler
+ * that only has access to thisCommand. Avoids structural casts.
+ */
+declare const readMergedOptions: (cmd: Command) => GetDotenvCliOptions | undefined;
+
+export { GetDotenvCli, definePlugin, readMergedOptions };
+export type { DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, ScriptsTable };

package/dist/cliHost.mjs

@@ -1,9 +1,9 @@
 import { Command } from 'commander';
 import fs from 'fs-extra';
 import { packageDirectory } from 'package-directory';
+import url, { fileURLToPath, pathToFileURL } from 'url';
 import path, { join, extname } from 'path';
 import { z } from 'zod';
-import url, { fileURLToPath, pathToFileURL } from 'url';
 import YAML from 'yaml';
 import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
@@ -981,6 +981,8 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
 
 const HOST_META_URL = import.meta.url;
 const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
+const OPTS_SYMBOL = Symbol('GetDotenvCli.options');
+const HELP_HEADER_SYMBOL = Symbol('GetDotenvCli.helpHeader');
 /**
  * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
  *
@@ -997,15 +999,33 @@ class GetDotenvCli extends Command {
     _plugins = [];
     /** One-time installation guard */
     _installed = false;
+    /** Optional header line to prepend in help output */
+    [HELP_HEADER_SYMBOL];
     constructor(alias = 'getdotenv') {
         super(alias);
         // Ensure subcommands that use passThroughOptions can be attached safely.
         // Commander requires parent commands to enable positional options when a
         // child uses passThroughOptions.
         this.enablePositionalOptions();
+        // Configure grouped help: show only base options in default "Options";
+        // append App/Plugin sections after default help.
+        this.configureHelp({
+            visibleOptions: (cmd) => {
+                const all = cmd.options ??
+                    [];
+                return all.filter((opt) => {
+                    const group = opt.__group;
+                    return group === 'base';
+                });
+            },
+        });
+        this.addHelpText('beforeAll', () => {
+            const header = this[HELP_HEADER_SYMBOL];
+            return header && header.length > 0 ? `${header}\n\n` : '';
+        });
+        this.addHelpText('afterAll', (ctx) => this.#renderOptionGroups(ctx.command));
         // Skeleton preSubcommand hook: produce a context if absent, without
-        // mutating process.env. The passOptions hook (when installed) will
-        // compute the final context using merged CLI options; keeping
+        // mutating process.env. The passOptions hook (when installed) will    // compute the final context using merged CLI options; keeping
         // loadProcess=false here avoids leaking dotenv values into the parent
         // process env before subcommands execute.
         this.hook('preSubcommand', async () => {
@@ -1037,11 +1057,96 @@ class GetDotenvCli extends Command {
     getCtx() {
         return this[CTX_SYMBOL];
     }
+    /**
+     * Retrieve the merged root CLI options bag (if set by passOptions()).
+     * Downstream-safe: no generics required.
+     */
+    getOptions() {
+        return this[OPTS_SYMBOL];
+    }
+    /** Internal: set the merged root options bag for this run. */
+    _setOptionsBag(bag) {
+        this[OPTS_SYMBOL] = bag;
+    }
     /**   * Convenience helper to create a namespaced subcommand.
      */
     ns(name) {
         return this.command(name);
     }
+    /**
+     * Tag options added during the provided callback as 'app' for grouped help.
+     * Allows downstream apps to demarcate their root-level options.
+     */
+    tagAppOptions(fn) {
+        const root = this;
+        const originalAddOption = root.addOption.bind(root);
+        const originalOption = root.option.bind(root);
+        const tagLatest = (cmd, group) => {
+            const optsArr = cmd.options;
+            if (Array.isArray(optsArr) && optsArr.length > 0) {
+                const last = optsArr[optsArr.length - 1];
+                last.__group = group;
+            }
+        };
+        root.addOption = function patchedAdd(opt) {
+            opt.__group = 'app';
+            return originalAddOption(opt);
+        };
+        root.option = function patchedOption(...args) {
+            const ret = originalOption(...args);
+            tagLatest(this, 'app');
+            return ret;
+        };
+        try {
+            return fn(root);
+        }
+        finally {
+            root.addOption = originalAddOption;
+            root.option = originalOption;
+        }
+    }
+    /**
+     * Branding helper: set CLI name/description/version and optional help header.
+     * If version is omitted and importMetaUrl is provided, attempts to read the
+     * nearest package.json version (best-effort; non-fatal on failure).
+     */
+    async brand(args) {
+        const { name, description, version, importMetaUrl, helpHeader } = args;
+        if (typeof name === 'string' && name.length > 0)
+            this.name(name);
+        if (typeof description === 'string')
+            this.description(description);
+        let v = version;
+        if (!v && importMetaUrl) {
+            try {
+                const fromUrl = fileURLToPath(importMetaUrl);
+                const pkgDir = await packageDirectory({ cwd: fromUrl });
+                if (pkgDir) {
+                    const txt = await fs.readFile(`${pkgDir}/package.json`, 'utf-8');
+                    const pkg = JSON.parse(txt);
+                    if (pkg.version)
+                        v = pkg.version;
+                }
+            }
+            catch {
+                // best-effort only
+            }
+        }
+        if (v)
+            this.version(v);
+        // Help header:
+        // - If caller provides helpHeader, use it.
+        // - Otherwise, when a version is known, default to "<name> v<version>".
+        if (typeof helpHeader === 'string') {
+            this[HELP_HEADER_SYMBOL] = helpHeader;
+        }
+        else if (v) {
+            // Use the current command name (possibly overridden by 'name' above).
+            const header = `${this.name()} v${v}`;
+            this[HELP_HEADER_SYMBOL] = header;
+        }
+        return this;
+    }
     /**
      * Register a plugin for installation (parent level).
      * Installation occurs on first resolveAndLoad() (or explicit install()).
@@ -1080,6 +1185,69 @@ class GetDotenvCli extends Command {
         for (const p of this._plugins)
             await run(p);
     }
+    // Render App/Plugin grouped options appended after default help.
+    #renderOptionGroups(cmd) {
+        const all = cmd.options ?? [];
+        const byGroup = new Map();
+        for (const o of all) {
+            const opt = o;
+            const g = opt.__group;
+            if (!g || g === 'base')
+                continue; // base handled by default help
+            const rows = byGroup.get(g) ?? [];
+            rows.push({
+                flags: opt.flags ?? '',
+                description: opt.description ?? '',
+            });
+            byGroup.set(g, rows);
+        }
+        if (byGroup.size === 0)
+            return '';
+        const renderRows = (title, rows) => {
+            const width = Math.min(40, rows.reduce((m, r) => Math.max(m, r.flags.length), 0));
+            const lines = rows
+                .map((r) => {
+                const pad = ' '.repeat(Math.max(2, width - r.flags.length + 2));
+                return `  ${r.flags}${pad}${r.description}`.trimEnd();
+            })
+                .join('\n');
+            return `\n${title}:\n${lines}\n`;
+        };
+        let out = '';
+        // App options (if any)
+        const app = byGroup.get('app');
+        if (app && app.length > 0) {
+            out += renderRows('App options', app);
+        }
+        // Plugin groups sorted by id
+        const pluginKeys = Array.from(byGroup.keys()).filter((k) => k.startsWith('plugin:'));
+        pluginKeys.sort((a, b) => a.localeCompare(b));
+        for (const k of pluginKeys) {
+            const id = k.slice('plugin:'.length) || '(unknown)';
+            const rows = byGroup.get(k) ?? [];
+            if (rows.length > 0) {
+                out += renderRows(`Plugin options — ${id}`, rows);
+            }
+        }
+        return out;
+    }
 }
 
-export { GetDotenvCli, definePlugin };
+/**
+ * Helper to retrieve the merged root options bag from any action handler
+ * that only has access to thisCommand. Avoids structural casts.
+ */
+const readMergedOptions = (cmd) => {
+    // Ascend to the root command
+    let root = cmd;
+    while (root.parent) {
+        root = root.parent;
+    }
+    const hostAny = root;
+    return typeof hostAny.getOptions === 'function'
+        ? hostAny.getOptions()
+        : root
+            .getDotenvCliOptions;
+};
+
+export { GetDotenvCli, definePlugin, readMergedOptions };

package/dist/getdotenv.cli.mjs

@@ -2,9 +2,9 @@
 import { Command, Option } from 'commander';
 import fs from 'fs-extra';
 import { packageDirectory } from 'package-directory';
+import url, { fileURLToPath, pathToFileURL } from 'url';
 import path, { join, extname } from 'path';
 import { z } from 'zod';
-import url, { fileURLToPath, pathToFileURL } from 'url';
 import YAML from 'yaml';
 import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
@@ -981,6 +981,8 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
 
 const HOST_META_URL = import.meta.url;
 const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
+const OPTS_SYMBOL = Symbol('GetDotenvCli.options');
+const HELP_HEADER_SYMBOL = Symbol('GetDotenvCli.helpHeader');
 /**
  * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
  *
@@ -997,15 +999,33 @@ class GetDotenvCli extends Command {
     _plugins = [];
     /** One-time installation guard */
     _installed = false;
+    /** Optional header line to prepend in help output */
+    [HELP_HEADER_SYMBOL];
     constructor(alias = 'getdotenv') {
         super(alias);
         // Ensure subcommands that use passThroughOptions can be attached safely.
         // Commander requires parent commands to enable positional options when a
         // child uses passThroughOptions.
         this.enablePositionalOptions();
+        // Configure grouped help: show only base options in default "Options";
+        // append App/Plugin sections after default help.
+        this.configureHelp({
+            visibleOptions: (cmd) => {
+                const all = cmd.options ??
+                    [];
+                return all.filter((opt) => {
+                    const group = opt.__group;
+                    return group === 'base';
+                });
+            },
+        });
+        this.addHelpText('beforeAll', () => {
+            const header = this[HELP_HEADER_SYMBOL];
+            return header && header.length > 0 ? `${header}\n\n` : '';
+        });
+        this.addHelpText('afterAll', (ctx) => this.#renderOptionGroups(ctx.command));
         // Skeleton preSubcommand hook: produce a context if absent, without
-        // mutating process.env. The passOptions hook (when installed) will
-        // compute the final context using merged CLI options; keeping
+        // mutating process.env. The passOptions hook (when installed) will    // compute the final context using merged CLI options; keeping
         // loadProcess=false here avoids leaking dotenv values into the parent
         // process env before subcommands execute.
         this.hook('preSubcommand', async () => {
@@ -1037,11 +1057,96 @@ class GetDotenvCli extends Command {
     getCtx() {
         return this[CTX_SYMBOL];
     }
+    /**
+     * Retrieve the merged root CLI options bag (if set by passOptions()).
+     * Downstream-safe: no generics required.
+     */
+    getOptions() {
+        return this[OPTS_SYMBOL];
+    }
+    /** Internal: set the merged root options bag for this run. */
+    _setOptionsBag(bag) {
+        this[OPTS_SYMBOL] = bag;
+    }
     /**   * Convenience helper to create a namespaced subcommand.
      */
     ns(name) {
         return this.command(name);
     }
+    /**
+     * Tag options added during the provided callback as 'app' for grouped help.
+     * Allows downstream apps to demarcate their root-level options.
+     */
+    tagAppOptions(fn) {
+        const root = this;
+        const originalAddOption = root.addOption.bind(root);
+        const originalOption = root.option.bind(root);
+        const tagLatest = (cmd, group) => {
+            const optsArr = cmd.options;
+            if (Array.isArray(optsArr) && optsArr.length > 0) {
+                const last = optsArr[optsArr.length - 1];
+                last.__group = group;
+            }
+        };
+        root.addOption = function patchedAdd(opt) {
+            opt.__group = 'app';
+            return originalAddOption(opt);
+        };
+        root.option = function patchedOption(...args) {
+            const ret = originalOption(...args);
+            tagLatest(this, 'app');
+            return ret;
+        };
+        try {
+            return fn(root);
+        }
+        finally {
+            root.addOption = originalAddOption;
+            root.option = originalOption;
+        }
+    }
+    /**
+     * Branding helper: set CLI name/description/version and optional help header.
+     * If version is omitted and importMetaUrl is provided, attempts to read the
+     * nearest package.json version (best-effort; non-fatal on failure).
+     */
+    async brand(args) {
+        const { name, description, version, importMetaUrl, helpHeader } = args;
+        if (typeof name === 'string' && name.length > 0)
+            this.name(name);
+        if (typeof description === 'string')
+            this.description(description);
+        let v = version;
+        if (!v && importMetaUrl) {
+            try {
+                const fromUrl = fileURLToPath(importMetaUrl);
+                const pkgDir = await packageDirectory({ cwd: fromUrl });
+                if (pkgDir) {
+                    const txt = await fs.readFile(`${pkgDir}/package.json`, 'utf-8');
+                    const pkg = JSON.parse(txt);
+                    if (pkg.version)
+                        v = pkg.version;
+                }
+            }
+            catch {
+                // best-effort only
+            }
+        }
+        if (v)
+            this.version(v);
+        // Help header:
+        // - If caller provides helpHeader, use it.
+        // - Otherwise, when a version is known, default to "<name> v<version>".
+        if (typeof helpHeader === 'string') {
+            this[HELP_HEADER_SYMBOL] = helpHeader;
+        }
+        else if (v) {
+            // Use the current command name (possibly overridden by 'name' above).
+            const header = `${this.name()} v${v}`;
+            this[HELP_HEADER_SYMBOL] = header;
+        }
+        return this;
+    }
     /**
      * Register a plugin for installation (parent level).
      * Installation occurs on first resolveAndLoad() (or explicit install()).
@@ -1080,6 +1185,52 @@ class GetDotenvCli extends Command {
         for (const p of this._plugins)
             await run(p);
     }
+    // Render App/Plugin grouped options appended after default help.
+    #renderOptionGroups(cmd) {
+        const all = cmd.options ?? [];
+        const byGroup = new Map();
+        for (const o of all) {
+            const opt = o;
+            const g = opt.__group;
+            if (!g || g === 'base')
+                continue; // base handled by default help
+            const rows = byGroup.get(g) ?? [];
+            rows.push({
+                flags: opt.flags ?? '',
+                description: opt.description ?? '',
+            });
+            byGroup.set(g, rows);
+        }
+        if (byGroup.size === 0)
+            return '';
+        const renderRows = (title, rows) => {
+            const width = Math.min(40, rows.reduce((m, r) => Math.max(m, r.flags.length), 0));
+            const lines = rows
+                .map((r) => {
+                const pad = ' '.repeat(Math.max(2, width - r.flags.length + 2));
+                return `  ${r.flags}${pad}${r.description}`.trimEnd();
+            })
+                .join('\n');
+            return `\n${title}:\n${lines}\n`;
+        };
+        let out = '';
+        // App options (if any)
+        const app = byGroup.get('app');
+        if (app && app.length > 0) {
+            out += renderRows('App options', app);
+        }
+        // Plugin groups sorted by id
+        const pluginKeys = Array.from(byGroup.keys()).filter((k) => k.startsWith('plugin:'));
+        pluginKeys.sort((a, b) => a.localeCompare(b));
+        for (const k of pluginKeys) {
+            const id = k.slice('plugin:'.length) || '(unknown)';
+            const rows = byGroup.get(k) ?? [];
+            if (rows.length > 0) {
+                out += renderRows(`Plugin options — ${id}`, rows);
+            }
+        }
+        return out;
+    }
 }
 
 /**
@@ -1087,6 +1238,28 @@ class GetDotenvCli extends Command {
  * Uses provided defaults to render help labels without coupling to generators.
  */
 const attachRootOptions = (program, defaults, opts) => {
+    // Install temporary wrappers to tag all options added here as "base".
+    const GROUP = 'base';
+    const tagLatest = (cmd, group) => {
+        const optsArr = cmd.options;
+        if (Array.isArray(optsArr) && optsArr.length > 0) {
+            const last = optsArr[optsArr.length - 1];
+            last.__group = group;
+        }
+    };
+    const originalAddOption = program.addOption.bind(program);
+    const originalOption = program.option.bind(program);
+    program.addOption = function patchedAdd(opt) {
+        // Tag before adding, in case consumers inspect the Option directly.
+        opt.__group = GROUP;
+        const ret = originalAddOption(opt);
+        return ret;
+    };
+    program.option = function patchedOption(...args) {
+        const ret = originalOption(...args);
+        tagLatest(this, GROUP);
+        return ret;
+    };
     const { defaultEnv, dotenvToken, dynamicPath, env, excludeDynamic, excludeEnv, excludeGlobal, excludePrivate, excludePublic, loadProcess, log, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, shell, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
     const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
     const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
@@ -1159,6 +1332,9 @@ const attachRootOptions = (program, defaults, opts) => {
         .hideHelp());
     // Diagnostics: opt-in tracing; optional variadic keys after the flag.
     p = p.option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)');
+    // Restore original methods to avoid tagging future additions outside base.
+    program.addOption = originalAddOption;
+    program.option = originalOption;
     return p;
 };
 
@@ -1298,6 +1474,8 @@ GetDotenvCli.prototype.passOptions = function (defaults) {
         // Persist merged options for nested invocations (batch exec).
         thisCommand.getDotenvCliOptions =
             merged;
+        // Also store on the host for downstream ergonomic accessors.
+        this._setOptionsBag(merged);
         // Build service options and compute context (always-on config loader path).
         const serviceOptions = getDotenvCliOptions2Options(merged);
         await this.resolveAndLoad(serviceOptions);
@@ -1309,6 +1487,7 @@ GetDotenvCli.prototype.passOptions = function (defaults) {
         const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
         thisCommand.getDotenvCliOptions =
             merged;
+        this._setOptionsBag(merged);
         // Avoid duplicate heavy work if a context is already present.
         if (!this.getCtx()) {
             const serviceOptions = getDotenvCliOptions2Options(merged);
@@ -2329,6 +2508,17 @@ const attachParentAlias = (cli, options, _cmd) => {
     const desc = aliasSpec.description ??
         'alias of cmd subcommand; provide command tokens (variadic)';
     cli.option(aliasSpec.flags, desc);
+    // Tag the just-added parent option for grouped help rendering.
+    try {
+        const optsArr = cli.options;
+        if (Array.isArray(optsArr) && optsArr.length > 0) {
+            const last = optsArr[optsArr.length - 1];
+            last.__group = 'plugin:cmd';
+        }
+    }
+    catch {
+        /* noop */
+    }
     // Shared alias executor for either preAction or preSubcommand hooks.
     // Ensure we only execute once even if both hooks fire in a single parse.
     let aliasHandled = false;
@@ -3059,7 +3249,13 @@ const initPlugin = (opts = {}) => definePlugin({
 });
 
 // Shipped CLI rebased on plugin-first host.
-const program = new GetDotenvCli('getdotenv')
+const program = new GetDotenvCli('getdotenv');
+// Brand the shipped CLI so help shows the package version (e.g., "getdotenv v5.0.0").
+await program.brand({
+    importMetaUrl: import.meta.url,
+    description: 'Base CLI.',
+});
+program
     .attachRootOptions({ loadProcess: false })
     .use(cmdPlugin({ asDefault: true, optionAlias: '-c, --cmd <command...>' }))
     .use(batchPlugin())