@karmaniverous/get-dotenv 7.0.7 → 7.0.9

package/dist/cli.mjs

@@ -1,7 +1,7 @@
-export { c as createCli } from './chunks/createCli-DRgcaM2D.mjs';
+export { c as createCli } from './chunks/createCli-CCxTLJ1j.mjs';
 import 'zod';
 import 'path';
-import './chunks/loader-V1vbmtyw.mjs';
+import './chunks/loader-C3DtD6HB.mjs';
 import 'fs-extra';
 import 'package-directory';
 import 'url';
@@ -13,27 +13,22 @@ import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
 import '@commander-js/extra-typings';
 import 'nanoid';
-import './chunks/readMergedOptions-x80ltQO_.mjs';
-import './chunks/readDotenvCascade-Dgx4SC1p.mjs';
+import './chunks/readMergedOptions-_hjyCNZ7.mjs';
+import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import 'dotenv';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-CR-BEUmS.mjs';
+import './chunks/resolveCliOptions-Dp7wPY1K.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
-import './chunks/spawnEnv-CKgnHGpr.mjs';
-import './chunks/index-4kbkrHS9.mjs';
-import 'node:os';
-import 'node:fs/promises';
-import 'node:stream';
-import 'node:crypto';
-import 'node:fs';
-import 'node:https';
-import 'node:process';
+import './chunks/spawnEnv-DvisqPiU.mjs';
+import './chunks/index-Cay5Gzhu.mjs';
 import './plugins-batch.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
 import 'globby';
-import './chunks/index-BzoCat8h.mjs';
+import 'os';
+import './chunks/index-xqvxTkr9.mjs';
 import './plugins-init.mjs';
+import 'node:process';
 import 'readline/promises';
 import 'node:url';

package/dist/cliHost.d.ts

@@ -287,7 +287,7 @@ interface RootOptionsShape {
      */
     trace?: boolean | string[];
     /** Paths to search for dotenv files (space-delimited string or array). */
-    paths?: string;
+    paths?: string | string[];
     /** Delimiter for paths string (default: space). */
     pathsDelimiter?: string;
     /** Regex pattern for paths delimiter. */
@@ -384,7 +384,7 @@ type ProcessEnv = Record<string, string | undefined>;
  * and the selected environment (if any), and returns either a string to set
  * or `undefined` to unset/skip the variable.
  */
-type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | undefined;
+type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | null | undefined;
 /**
  * A map of dynamic variable definitions.
  * Keys are variable names; values are either literal strings or functions.
@@ -903,10 +903,14 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions,
     install(): Promise<void>;
     /**
      * Run afterResolve hooks for registered plugins (parent → children).
-     * When {@link invokedSubcommand} is provided, only the matching plugin
-     * subtree runs; otherwise all plugins run (backward compatibility).
+     * When {@link commandPath} is provided, only the matching branch of the
+     * plugin tree runs; otherwise all plugins run (backward compatibility).
+     *
+     * The path is walked segment-by-segment against the plugin tree.
+     * Intermediate matches run their own afterResolve hook.
+     * The deepest match runs afterResolve for itself and all its descendants.
      */
-    private _runAfterResolve;
+    _runAfterResolve(ctx: GetDotenvCliCtx<TOptions>, commandPath?: string[]): Promise<void>;
 }
 
 /** src/cliHost/getRootCommand.ts

package/dist/cliHost.mjs

@@ -1,12 +1,12 @@
-export { G as GetDotenvCli, g as definePlugin, r as readMergedOptions } from './chunks/readMergedOptions-x80ltQO_.mjs';
-export { b as buildSpawnEnv, r as resolveCommand, a as resolveShell, c as runCommand, d as runCommandResult, s as shouldCapture } from './chunks/spawnEnv-CKgnHGpr.mjs';
-export { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './chunks/resolveCliOptions-CR-BEUmS.mjs';
-export { d as defineScripts, g as groupPlugins } from './chunks/types-poB1VAs_.mjs';
+export { G as GetDotenvCli, d as definePlugin, r as readMergedOptions } from './chunks/readMergedOptions-_hjyCNZ7.mjs';
+export { b as buildSpawnEnv, r as resolveCommand, a as resolveShell, c as runCommand, d as runCommandResult, s as shouldCapture } from './chunks/spawnEnv-DvisqPiU.mjs';
+export { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './chunks/resolveCliOptions-Dp7wPY1K.mjs';
+export { d as defineScripts, g as groupPlugins } from './chunks/types-zXDNhcST.mjs';
 export { t as toHelpConfig } from './chunks/helpConfig-CGejgwWW.mjs';
 export { c as composeNestedEnv, m as maybePreserveNodeEvalArgv, s as stripOne } from './chunks/invoke-DuRPU1oC.mjs';
 export { z } from 'zod';
 import '@commander-js/extra-typings';
-import './chunks/readDotenvCascade-Dgx4SC1p.mjs';
+import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import 'fs-extra';
 import 'radash';
 import 'node:buffer';
@@ -17,7 +17,7 @@ import 'path';
 import 'url';
 import 'dotenv';
 import 'nanoid';
-import './chunks/loader-V1vbmtyw.mjs';
+import './chunks/loader-C3DtD6HB.mjs';
 import 'package-directory';
 import 'yaml';
 import 'execa';

package/dist/config.d.ts

@@ -69,7 +69,7 @@ interface RootOptionsShape {
      */
     trace?: boolean | string[];
     /** Paths to search for dotenv files (space-delimited string or array). */
-    paths?: string;
+    paths?: string | string[];
     /** Delimiter for paths string (default: space). */
     pathsDelimiter?: string;
     /** Regex pattern for paths delimiter. */

package/dist/config.mjs

@@ -1,4 +1,4 @@
-export { d as discoverConfigFiles, l as loadConfigFile, r as resolveGetDotenvConfigSources, t as toFileUrl } from './chunks/loader-V1vbmtyw.mjs';
+export { d as discoverConfigFiles, l as loadConfigFile, r as resolveGetDotenvConfigSources, t as toFileUrl } from './chunks/loader-C3DtD6HB.mjs';
 export { v as validateEnvAgainstSources } from './chunks/validate-CDl0rE6k.mjs';
 import 'fs-extra';
 import 'package-directory';

package/dist/env-overlay.d.ts

@@ -69,7 +69,7 @@ interface RootOptionsShape {
      */
     trace?: boolean | string[];
     /** Paths to search for dotenv files (space-delimited string or array). */
-    paths?: string;
+    paths?: string | string[];
     /** Delimiter for paths string (default: space). */
     pathsDelimiter?: string;
     /** Regex pattern for paths delimiter. */
@@ -165,7 +165,7 @@ type ProcessEnv = Record<string, string | undefined>;
  * and the selected environment (if any), and returns either a string to set
  * or `undefined` to unset/skip the variable.
  */
-type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | undefined;
+type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | null | undefined;
 /**
  * A map of dynamic variable definitions.
  * Keys are variable names; values are either literal strings or functions.
@@ -318,15 +318,17 @@ declare function pushDotenvProvenance(prov: DotenvProvenance, key: string, entry
 
 /**
  * Apply a dynamic map to the target progressively.
- * - Functions receive (target, env) and may return string | undefined.
- * - Literals are assigned directly (including undefined).
+ * - Functions receive (target, env) and may return string | null | undefined.
+ * - string → set the key to that value.
+ * - undefined → no-op, leave existing value unchanged.
+ * - null → delete the key from the target.
  *
  * @param target - Mutable target environment to assign into.
  * @param map - Dynamic map to apply (functions and/or literal values).
  * @param env - Selected environment name (if any) passed through to dynamic functions.
- * @returns Nothing.
+ * @returns Set of keys that were deleted (value was null).
  */
-declare function applyDynamicMap(target: ProcessEnv, map?: GetDotenvDynamic, env?: string): void;
+declare function applyDynamicMap(target: ProcessEnv, map?: GetDotenvDynamic, env?: string): Set<string>;
 /**
  * Load a default-export dynamic map from a JS/TS file (without applying it).
  *
@@ -357,12 +359,14 @@ declare function loadDynamicModuleDefault(absPath: string, cacheDirName: string)
  * @param prov - Provenance map to append into.
  * @param meta - Dynamic provenance metadata (source tier and optional dynamicPath).
  *
+ * @returns Set of keys that were deleted (value was null).
+ *
  * @public
  */
 declare function applyDynamicMapWithProvenance(target: ProcessEnv, map: GetDotenvDynamic | undefined, env: string | undefined, prov: DotenvProvenance, meta: {
     dynamicSource: DotenvDynamicSource;
     dynamicPath?: string;
-}): void;
+}): Set<string>;
 /**
  * Load a default-export dynamic map from a JS/TS file and apply it.
  * Uses util/loadModuleDefault for robust TS handling (direct import, esbuild,
@@ -376,9 +380,9 @@ declare function applyDynamicMapWithProvenance(target: ProcessEnv, map: GetDoten
  * @param absPath - Absolute path to the dynamic module file.
  * @param env - Selected environment name (if any).
  * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
- * @returns A `Promise\<void\>` which resolves after the module (if present) has been applied.
+ * @returns A `Promise\<Set\<string\>\>` resolving to the set of deleted keys.
  */
-declare function loadAndApplyDynamic(target: ProcessEnv, absPath: string, env: string | undefined, cacheDirName: string): Promise<void>;
+declare function loadAndApplyDynamic(target: ProcessEnv, absPath: string, env: string | undefined, cacheDirName: string): Promise<Set<string>>;
 
 /**
  * Configuration sources for environment overlay.

package/dist/env-overlay.mjs

@@ -1,5 +1,5 @@
-import { e as dotenvExpandAll } from './chunks/readDotenvCascade-Dgx4SC1p.mjs';
-export { a as applyDynamicMap, b as applyDynamicMapWithProvenance, c as createDotenvProvenance, l as loadAndApplyDynamic, g as loadDynamicModuleDefault, o as overlayEnvWithProvenance, p as pushDotenvProvenance, h as readDotenvCascadeWithProvenance } from './chunks/readDotenvCascade-Dgx4SC1p.mjs';
+import { d as dotenvExpandAll } from './chunks/readDotenvCascade-CfFPgLCp.mjs';
+export { a as applyDynamicMap, b as applyDynamicMapWithProvenance, c as createDotenvProvenance, l as loadAndApplyDynamic, e as loadDynamicModuleDefault, o as overlayEnvWithProvenance, p as pushDotenvProvenance, r as readDotenvCascadeWithProvenance } from './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import 'fs-extra';
 import 'node:path';
 import 'radash';

package/dist/getdotenv.cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { c as createCli } from './chunks/createCli-DRgcaM2D.mjs';
+import { c as createCli } from './chunks/createCli-CCxTLJ1j.mjs';
 import 'zod';
 import 'path';
-import './chunks/loader-V1vbmtyw.mjs';
+import './chunks/loader-C3DtD6HB.mjs';
 import 'fs-extra';
 import 'package-directory';
 import 'url';
@@ -14,28 +14,23 @@ import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
 import '@commander-js/extra-typings';
 import 'nanoid';
-import './chunks/readMergedOptions-x80ltQO_.mjs';
-import './chunks/readDotenvCascade-Dgx4SC1p.mjs';
+import './chunks/readMergedOptions-_hjyCNZ7.mjs';
+import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import 'dotenv';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-CR-BEUmS.mjs';
+import './chunks/resolveCliOptions-Dp7wPY1K.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
-import './chunks/spawnEnv-CKgnHGpr.mjs';
-import './chunks/index-4kbkrHS9.mjs';
-import 'node:os';
-import 'node:fs/promises';
-import 'node:stream';
-import 'node:crypto';
-import 'node:fs';
-import 'node:https';
-import 'node:process';
+import './chunks/spawnEnv-DvisqPiU.mjs';
+import './chunks/index-Cay5Gzhu.mjs';
 import './plugins-batch.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
 import 'globby';
-import './chunks/index-BzoCat8h.mjs';
+import 'os';
+import './chunks/index-xqvxTkr9.mjs';
 import './plugins-init.mjs';
+import 'node:process';
 import 'readline/promises';
 import 'node:url';
 

package/dist/index.d.ts

@@ -286,7 +286,7 @@ interface RootOptionsShape {
      */
     trace?: boolean | string[];
     /** Paths to search for dotenv files (space-delimited string or array). */
-    paths?: string;
+    paths?: string | string[];
     /** Delimiter for paths string (default: space). */
     pathsDelimiter?: string;
     /** Regex pattern for paths delimiter. */
@@ -398,7 +398,7 @@ type RootOptionsShapeCompat = Omit<RootOptionsShape, 'vars' | 'paths'> & {
  * and the selected environment (if any), and returns either a string to set
  * or `undefined` to unset/skip the variable.
  */
-type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | undefined;
+type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | null | undefined;
 /**
  * A map of dynamic variable definitions.
  * Keys are variable names; values are either literal strings or functions.
@@ -433,7 +433,7 @@ type GetDotenvOptions = Omit<z.output<typeof getDotenvOptionsSchemaResolved>, 'l
  * Vars-aware dynamic helpers (compile-time DX).
  * DynamicFn: receive the current expanded variables and optional env.
  */
-type DynamicFn<Vars extends ProcessEnv> = (vars: Vars, env?: string) => string | undefined;
+type DynamicFn<Vars extends ProcessEnv> = (vars: Vars, env?: string) => string | null | undefined;
 /**
  * Vars-aware dynamic map type used by {@link defineDynamic} and JS/TS configs.
  *
@@ -952,10 +952,14 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions,
     install(): Promise<void>;
     /**
      * Run afterResolve hooks for registered plugins (parent → children).
-     * When {@link invokedSubcommand} is provided, only the matching plugin
-     * subtree runs; otherwise all plugins run (backward compatibility).
+     * When {@link commandPath} is provided, only the matching branch of the
+     * plugin tree runs; otherwise all plugins run (backward compatibility).
+     *
+     * The path is walked segment-by-segment against the plugin tree.
+     * Intermediate matches run their own afterResolve hook.
+     * The deepest match runs afterResolve for itself and all its descendants.
      */
-    private _runAfterResolve;
+    _runAfterResolve(ctx: GetDotenvCliCtx<TOptions>, commandPath?: string[]): Promise<void>;
 }
 
 /**

package/dist/index.mjs

@@ -1,8 +1,8 @@
-export { c as createCli } from './chunks/createCli-DRgcaM2D.mjs';
-import { j as resolveGetDotenvOptions, w as writeDotenvFile } from './chunks/readMergedOptions-x80ltQO_.mjs';
-export { G as GetDotenvCli, a as assertLogger, c as baseRootOptionDefaults, d as defaultsDeep, e as defineDynamic, f as defineGetDotenvConfig, g as definePlugin, h as getDotenvCliOptions2Options, i as interpolateDeep, r as readMergedOptions } from './chunks/readMergedOptions-x80ltQO_.mjs';
-export { b as buildSpawnEnv, s as shouldCapture, t as tokenize } from './chunks/spawnEnv-CKgnHGpr.mjs';
-export { d as defineScripts, g as groupPlugins } from './chunks/types-poB1VAs_.mjs';
+export { c as createCli } from './chunks/createCli-CCxTLJ1j.mjs';
+import { e as resolveGetDotenvOptions, w as writeDotenvFile } from './chunks/readMergedOptions-_hjyCNZ7.mjs';
+export { G as GetDotenvCli, f as assertLogger, b as baseRootOptionDefaults, a as defaultsDeep, h as defineDynamic, i as defineGetDotenvConfig, d as definePlugin, g as getDotenvCliOptions2Options, j as interpolateDeep, r as readMergedOptions } from './chunks/readMergedOptions-_hjyCNZ7.mjs';
+export { b as buildSpawnEnv, s as shouldCapture, t as tokenize } from './chunks/spawnEnv-DvisqPiU.mjs';
+export { d as defineScripts, g as groupPlugins } from './chunks/types-zXDNhcST.mjs';
 import { omit, pick } from 'radash';
 import { Buffer } from 'node:buffer';
 export { l as loadModuleDefault } from './chunks/loadModuleDefault-Dj8B3Stt.mjs';
@@ -10,35 +10,30 @@ import { InvalidArgumentError } from '@commander-js/extra-typings';
 import 'zod';
 import { nanoid } from 'nanoid';
 import path$1 from 'path';
-import { a as redactObject, m as maybeWarnEntropy } from './chunks/index-BzoCat8h.mjs';
-export { r as redactDisplay, t as traceChildEnv } from './chunks/index-BzoCat8h.mjs';
-import { r as readDotenv, e as dotenvExpandAll, a as applyDynamicMap, l as loadAndApplyDynamic } from './chunks/readDotenvCascade-Dgx4SC1p.mjs';
-export { d as dotenvExpand, f as dotenvExpandFromProcessEnv } from './chunks/readDotenvCascade-Dgx4SC1p.mjs';
+import { r as redactObject, m as maybeWarnEntropy } from './chunks/index-xqvxTkr9.mjs';
+export { a as redactDisplay, t as traceChildEnv } from './chunks/index-xqvxTkr9.mjs';
+import { g as readDotenv, d as dotenvExpandAll, a as applyDynamicMap, l as loadAndApplyDynamic } from './chunks/readDotenvCascade-CfFPgLCp.mjs';
+export { h as dotenvExpand, f as dotenvExpandFromProcessEnv } from './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import fs from 'fs-extra';
 import path from 'node:path';
 import 'crypto';
 import 'url';
 import 'dotenv';
-import './chunks/loader-V1vbmtyw.mjs';
+import './chunks/loader-C3DtD6HB.mjs';
 import 'package-directory';
 import 'yaml';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-CR-BEUmS.mjs';
+import './chunks/resolveCliOptions-Dp7wPY1K.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
-import './chunks/index-4kbkrHS9.mjs';
-import 'node:os';
-import 'node:fs/promises';
-import 'node:stream';
-import 'node:crypto';
-import 'node:fs';
-import 'node:https';
-import 'node:process';
+import './chunks/index-Cay5Gzhu.mjs';
 import './plugins-batch.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
 import 'globby';
+import 'os';
 import './plugins-init.mjs';
+import 'node:process';
 import 'readline/promises';
 import 'node:url';
 
@@ -927,11 +922,13 @@ async function getDotenv(options = {}) {
         ...(outputPath ? { [outputKey]: outputPath } : {}),
     }, { progressive: true });
     // Process dynamic variables. Programmatic option takes precedence over path.
+    const deletedKeys = new Set();
     if (!excludeDynamic) {
         // A2 precedence: programmatic dynamic < dynamicPath (dynamicPath wins when present)
         if (options.dynamic && Object.keys(options.dynamic).length > 0) {
             try {
-                applyDynamicMap(dotenv, options.dynamic, env ?? defaultEnv);
+                for (const k of applyDynamicMap(dotenv, options.dynamic, env ?? defaultEnv))
+                    deletedKeys.add(k);
             }
             catch {
                 throw new Error(`Unable to evaluate dynamic variables.`);
@@ -940,7 +937,8 @@ async function getDotenv(options = {}) {
         // dynamicPath is evaluated even when programmatic `dynamic` is present.
         if (dynamicPath) {
             const absDynamicPath = path$1.resolve(dynamicPath);
-            await loadAndApplyDynamic(dotenv, absDynamicPath, env ?? defaultEnv, 'getdotenv-dynamic');
+            for (const k of await loadAndApplyDynamic(dotenv, absDynamicPath, env ?? defaultEnv, 'getdotenv-dynamic'))
+                deletedKeys.add(k);
         }
     }
     // Write output file.
@@ -989,8 +987,17 @@ async function getDotenv(options = {}) {
         }
     }
     // Load process.env.
-    if (loadProcess)
-        Object.assign(process.env, resultDotenv);
+    if (loadProcess) {
+        for (const key of deletedKeys) {
+            Reflect.deleteProperty(process.env, key);
+        }
+        for (const [key, value] of Object.entries(resultDotenv)) {
+            if (value === undefined)
+                Reflect.deleteProperty(process.env, key);
+            else
+                process.env[key] = value;
+        }
+    }
     return resultDotenv;
 }
 

package/dist/plugins-aws.d.ts

@@ -272,7 +272,7 @@ type ProcessEnv = Record<string, string | undefined>;
  * and the selected environment (if any), and returns either a string to set
  * or `undefined` to unset/skip the variable.
  */
-type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | undefined;
+type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | null | undefined;
 /**
  * A map of dynamic variable definitions.
  * Keys are variable names; values are either literal strings or functions.

package/dist/plugins-aws.mjs

@@ -1,4 +1,4 @@
-import { r as readMergedOptions, g as definePlugin } from './chunks/readMergedOptions-x80ltQO_.mjs';
+import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-_hjyCNZ7.mjs';
 import 'execa';
 import { isObject } from 'radash';
 import 'node:buffer';
@@ -10,12 +10,12 @@ import 'url';
 import '@commander-js/extra-typings';
 import 'nanoid';
 import 'dotenv';
-import './chunks/loader-V1vbmtyw.mjs';
+import './chunks/loader-C3DtD6HB.mjs';
 import 'package-directory';
 import 'yaml';
 import { z } from 'zod';
-import { c as runCommand, d as runCommandResult, s as shouldCapture, a as resolveShell, b as buildSpawnEnv } from './chunks/spawnEnv-CKgnHGpr.mjs';
-import './chunks/readDotenvCascade-Dgx4SC1p.mjs';
+import { c as runCommand, d as runCommandResult, s as shouldCapture, a as resolveShell, b as buildSpawnEnv } from './chunks/spawnEnv-DvisqPiU.mjs';
+import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 
 /**

package/dist/plugins-batch.d.ts

@@ -272,7 +272,7 @@ type ProcessEnv = Record<string, string | undefined>;
  * and the selected environment (if any), and returns either a string to set
  * or `undefined` to unset/skip the variable.
  */
-type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | undefined;
+type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | null | undefined;
 /**
  * A map of dynamic variable definitions.
  * Keys are variable names; values are either literal strings or functions.
@@ -561,6 +561,11 @@ interface ExecShellCommandBatchOptions {
      * an array is treated as argv for shell‑off execution.
      */
     command?: string | string[];
+    /**
+     * Maximum number of concurrent executions when {@link ExecShellCommandBatchOptions.parallel} is true.
+     * Defaults to {@link defaultConcurrency}.
+     */
+    concurrency?: number;
     /**
      * Merged root CLI options bag (JSON‑serializable) forwarded for nested composition
      * by downstream executors. Used to compute child overlays deterministically.
@@ -586,6 +591,11 @@ interface ExecShellCommandBatchOptions {
      * Logger used for headings, listings, and diagnostics.
      */
     logger: Logger;
+    /**
+     * When true, execute commands across discovered directories in parallel.
+     * Output is buffered per-directory and printed in discovery order.
+     */
+    parallel?: boolean;
     /**
      * Resolve the batch root from the nearest package directory instead of CWD.
      */
@@ -608,12 +618,16 @@ interface ExecShellCommandBatchOptions {
 interface BatchParentInvokerFlags {
     /** Command to execute. */
     command?: string;
+    /** Maximum concurrent executions in parallel mode. */
+    concurrency?: number;
     /** Space-delimited glob patterns. */
     globs?: string;
     /** List directories without executing. */
     list?: boolean;
     /** Ignore errors and continue. */
     ignoreErrors?: boolean;
+    /** Execute commands in parallel across directories. */
+    parallel?: boolean;
     /** Use package directory as root. */
     pkgCwd?: boolean;
     /** Root path for discovery. */
@@ -636,6 +650,7 @@ interface BatchCmdSubcommandOptions {
  * - scripts/shell: used to resolve command and shell behavior per script or global default.
  */
 declare const batchPlugin: (opts?: BatchPluginOptions) => PluginWithInstanceHelpers<GetDotenvOptions, {
+    concurrency?: number | undefined;
     scripts?: Record<string, string | {
         cmd: string;
         shell?: string | boolean | undefined;
@@ -643,6 +658,7 @@ declare const batchPlugin: (opts?: BatchPluginOptions) => PluginWithInstanceHelp
     shell?: string | boolean | undefined;
     rootPath?: string | undefined;
     globs?: string | undefined;
+    parallel?: boolean | undefined;
     pkgCwd?: boolean | undefined;
 }, [], {}, {}>;
 /**