@karmaniverous/get-dotenv 5.0.0 → 5.2.0

package/dist/plugins-batch.d.cts

@@ -95,6 +95,93 @@ interface GetDotenvOptions {
     useConfigLoader?: boolean;
 }
 
+type Scripts$1 = 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;
+    /**
+     * Strict mode: fail the run when env validation issues are detected
+     * (schema or requiredKeys). Warns by default when false or unset.
+     */
+    strict?: boolean;
+    /**
+     * Redaction (presentation): mask secret-like values in logs/trace.
+     */
+    redact?: boolean;
+    /**
+     * Entropy warnings (presentation): emit once-per-key warnings for high-entropy values.
+     */
+    warnEntropy?: boolean;
+    entropyThreshold?: number;
+    entropyMinLength?: number;
+    entropyWhitelist?: string[];
+    redactPatterns?: string[];
+    /**
+     * 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$1;
+    /**
+     * 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 +189,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 +202,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 +218,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()).

package/dist/plugins-batch.d.mts

@@ -95,6 +95,93 @@ interface GetDotenvOptions {
     useConfigLoader?: boolean;
 }
 
+type Scripts$1 = 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;
+    /**
+     * Strict mode: fail the run when env validation issues are detected
+     * (schema or requiredKeys). Warns by default when false or unset.
+     */
+    strict?: boolean;
+    /**
+     * Redaction (presentation): mask secret-like values in logs/trace.
+     */
+    redact?: boolean;
+    /**
+     * Entropy warnings (presentation): emit once-per-key warnings for high-entropy values.
+     */
+    warnEntropy?: boolean;
+    entropyThreshold?: number;
+    entropyMinLength?: number;
+    entropyWhitelist?: string[];
+    redactPatterns?: string[];
+    /**
+     * 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$1;
+    /**
+     * 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 +189,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 +202,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 +218,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()).

package/dist/plugins-batch.d.ts

@@ -95,6 +95,93 @@ interface GetDotenvOptions {
     useConfigLoader?: boolean;
 }
 
+type Scripts$1 = 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;
+    /**
+     * Strict mode: fail the run when env validation issues are detected
+     * (schema or requiredKeys). Warns by default when false or unset.
+     */
+    strict?: boolean;
+    /**
+     * Redaction (presentation): mask secret-like values in logs/trace.
+     */
+    redact?: boolean;
+    /**
+     * Entropy warnings (presentation): emit once-per-key warnings for high-entropy values.
+     */
+    warnEntropy?: boolean;
+    entropyThreshold?: number;
+    entropyMinLength?: number;
+    entropyWhitelist?: string[];
+    redactPatterns?: string[];
+    /**
+     * 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$1;
+    /**
+     * 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 +189,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 +202,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 +218,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()).

package/dist/plugins-batch.mjs

@@ -163,6 +163,48 @@ const runCommand = async (command, shell, opts) => {
     }
 };
 
+const dropUndefined = (bag) => Object.fromEntries(Object.entries(bag).filter((e) => typeof e[1] === 'string'));
+/** Build a sanitized env for child processes from base + overlay. */
+const buildSpawnEnv = (base, overlay) => {
+    const raw = {
+        ...(base ?? {}),
+        ...(overlay ?? {}),
+    };
+    // Drop undefined first
+    const entries = Object.entries(dropUndefined(raw));
+    if (process.platform === 'win32') {
+        // Windows: keys are case-insensitive; collapse duplicates
+        const byLower = new Map();
+        for (const [k, v] of entries) {
+            byLower.set(k.toLowerCase(), [k, v]); // last wins; preserve latest casing
+        }
+        const out = {};
+        for (const [, [k, v]] of byLower)
+            out[k] = v;
+        // HOME fallback from USERPROFILE (common expectation)
+        if (!Object.prototype.hasOwnProperty.call(out, 'HOME')) {
+            const up = out['USERPROFILE'];
+            if (typeof up === 'string' && up.length > 0)
+                out['HOME'] = up;
+        }
+        // Normalize TMP/TEMP coherence (pick any present; reflect to both)
+        const tmp = out['TMP'] ?? out['TEMP'];
+        if (typeof tmp === 'string' && tmp.length > 0) {
+            out['TMP'] = tmp;
+            out['TEMP'] = tmp;
+        }
+        return out;
+    }
+    // POSIX: keep keys as-is
+    const out = Object.fromEntries(entries);
+    // Ensure TMPDIR exists when any temp key is present (best-effort)
+    const tmpdir = out['TMPDIR'] ?? out['TMP'] ?? out['TEMP'];
+    if (typeof tmpdir === 'string' && tmpdir.length > 0) {
+        out['TMPDIR'] = tmpdir;
+    }
+    return out;
+};
+
 const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
     let cwd = process.cwd();
     if (pkgCwd) {
@@ -235,14 +277,12 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, igno
             const hasCmd = (typeof command === 'string' && command.length > 0) ||
                 (Array.isArray(command) && command.length > 0);
             if (hasCmd) {
+                const envBag = getDotenvCliOptions !== undefined
+                    ? { getDotenvCliOptions: JSON.stringify(getDotenvCliOptions) }
+                    : undefined;
                 await runCommand(command, shell, {
                     cwd: path,
-                    env: {
-                        ...process.env,
-                        getDotenvCliOptions: getDotenvCliOptions
-                            ? JSON.stringify(getDotenvCliOptions)
-                            : undefined,
-                    },
+                    env: buildSpawnEnv(process.env, envBag),
                     stdio: capture ? 'pipe' : 'inherit',
                 });
             }

package/dist/plugins-init.d.cts

@@ -95,6 +95,93 @@ 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;
+    /**
+     * Strict mode: fail the run when env validation issues are detected
+     * (schema or requiredKeys). Warns by default when false or unset.
+     */
+    strict?: boolean;
+    /**
+     * Redaction (presentation): mask secret-like values in logs/trace.
+     */
+    redact?: boolean;
+    /**
+     * Entropy warnings (presentation): emit once-per-key warnings for high-entropy values.
+     */
+    warnEntropy?: boolean;
+    entropyThreshold?: number;
+    entropyMinLength?: number;
+    entropyWhitelist?: string[];
+    redactPatterns?: string[];
+    /**
+     * 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 +189,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 +202,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 +218,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()).