@karmaniverous/get-dotenv 7.0.8 → 7.0.10

package/dist/chunks/{createCli-CUPiFVdZ.mjs → createCli-BIG9hp19.mjs}

@@ -6,19 +6,19 @@ import 'fs-extra';
 import 'node:path';
 import 'radash';
 import 'node:buffer';
-import { a as defaultsDeep, g as getDotenvCliOptions2Options, b as baseRootOptionDefaults, G as GetDotenvCli, c as attachRootOptions } from './readMergedOptions-BT1C87_u.mjs';
+import { a as defaultsDeep, g as getDotenvCliOptions2Options, b as baseRootOptionDefaults, G as GetDotenvCli, c as attachRootOptions } from './readMergedOptions-Bjl6rWXd.mjs';
 import 'crypto';
 import 'url';
 import '@commander-js/extra-typings';
 import 'dotenv';
 import 'execa';
 import { t as toHelpConfig } from './helpConfig-CGejgwWW.mjs';
-import { r as resolveCliOptions } from './resolveCliOptions-BbfouWSK.mjs';
+import { r as resolveCliOptions } from './resolveCliOptions-C0Jmb-6I.mjs';
 import { v as validateEnvAgainstSources } from './validate-CDl0rE6k.mjs';
 import { awsPlugin } from '../plugins-aws.mjs';
-import { a as awsWhoamiPlugin } from './index-CNXekCQC.mjs';
+import { a as awsWhoamiPlugin } from './index-DREvD42I.mjs';
 import { batchPlugin } from '../plugins-batch.mjs';
-import { c as cmdPlugin } from './index-DnG3N6yj.mjs';
+import { c as cmdPlugin } from './index-BAcAtESJ.mjs';
 import { initPlugin } from '../plugins-init.mjs';
 
 const dbg = (...args) => {
@@ -88,6 +88,10 @@ function installRootHooks(program, defaults) {
             runAfterResolve: false,
         });
         propagateResolvedEnv(merged);
+        // Propagate debug flag to env so dbg() helpers and error boundary see it.
+        if (merged.debug) {
+            process.env.GETDOTENV_DEBUG = '1';
+        }
         // Refresh dynamic help text using the resolved config slices.
         try {
             const ctx = program.getCtx();
@@ -140,6 +144,10 @@ function installRootHooks(program, defaults) {
         // builds a fresh `merged` and overwrites the options bag, so the env
         // propagated by preSubcommand is lost without this call.
         propagateResolvedEnv(merged);
+        // Propagate debug flag to env so dbg() helpers and error boundary see it.
+        if (merged.debug) {
+            process.env.GETDOTENV_DEBUG = '1';
+        }
         try {
             const ctx = program.getCtx();
             const helpCfg = toHelpConfig(merged, ctx.pluginConfigs);
@@ -273,6 +281,25 @@ function applyRootVisibility(program, visibility) {
     }
 }
 
+/**
+ * Top-level error boundary for the CLI runner.
+ *
+ * Presents errors as clean one-line messages by default.
+ * When GETDOTENV_DEBUG is set, prints the full stack trace.
+ */
+function handleCliError(err, argv) {
+    const isDebug = process.env.GETDOTENV_DEBUG === '1' ||
+        process.env.GETDOTENV_DEBUG === 'true' ||
+        (Array.isArray(argv) && argv.includes('--debug'));
+    const message = err instanceof Error ? err.message : String(err);
+    if (isDebug) {
+        console.error(err instanceof Error ? (err.stack ?? message) : message);
+    }
+    else {
+        console.error(`Error: ${message}`);
+    }
+    process.exitCode = 1;
+}
 /**
  * Create a configured get-dotenv CLI host.
  * Applies defaults, installs root hooks, and composes plugins.
@@ -365,7 +392,7 @@ function createCli(opts = {}) {
     }
     else {
         program
-            .use(cmdPlugin({ optionAlias: '-c, --cmd <command...>' }))
+            .use(cmdPlugin({ asDefault: true, optionAlias: '-c, --cmd <command...>' }))
             .use(batchPlugin())
             .use(awsPlugin().use(awsWhoamiPlugin()))
             .use(initPlugin());
@@ -468,7 +495,12 @@ function createCli(opts = {}) {
                 ? { helpHeader: opts.branding }
                 : {}),
         });
-        await program.parseAsync(['node', alias, ...argv]);
+        try {
+            await program.parseAsync(['node', alias, ...argv]);
+        }
+        catch (err) {
+            handleCliError(err, argv);
+        }
     };
 }
 

package/dist/chunks/{index-DnG3N6yj.mjs → index-BAcAtESJ.mjs}

@@ -1,5 +1,5 @@
 import { camel } from 'radash';
-import { r as readMergedOptions, a as defaultsDeep, g as getDotenvCliOptions2Options, d as definePlugin } from './readMergedOptions-BT1C87_u.mjs';
+import { r as readMergedOptions, a as defaultsDeep, g as getDotenvCliOptions2Options, d as definePlugin } from './readMergedOptions-Bjl6rWXd.mjs';
 import 'execa';
 import 'node:buffer';
 import 'fs-extra';
@@ -17,7 +17,7 @@ import { z } from 'zod';
 import { r as resolveCommand, a as resolveShell, t as tokenize, s as shouldCapture, c as runCommand, b as buildSpawnEnv } from './spawnEnv-DvisqPiU.mjs';
 import { m as maybePreserveNodeEvalArgv, c as composeNestedEnv, s as stripOne } from './invoke-DuRPU1oC.mjs';
 import { f as dotenvExpandFromProcessEnv } from './readDotenvCascade-CfFPgLCp.mjs';
-import { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './resolveCliOptions-BbfouWSK.mjs';
+import { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './resolveCliOptions-C0Jmb-6I.mjs';
 
 /** src/diagnostics/entropy.ts
  * Entropy diagnostics (presentation-only).
@@ -455,6 +455,7 @@ const cmdPluginConfigSchema = z
 const cmdPlugin = (options = {}) => {
     const plugin = definePlugin({
         ns: 'cmd',
+        ...(options.asDefault ? { nsOptions: { isDefault: true } } : {}),
         configSchema: cmdPluginConfigSchema,
         setup(cli) {
             const aliasSpec = typeof options.optionAlias === 'string'

package/dist/chunks/{index-CNXekCQC.mjs → index-DREvD42I.mjs}

@@ -1,4 +1,4 @@
-import { d as definePlugin } from './readMergedOptions-BT1C87_u.mjs';
+import { d as definePlugin } from './readMergedOptions-Bjl6rWXd.mjs';
 import 'execa';
 import 'radash';
 import 'node:buffer';
@@ -14,7 +14,6 @@ import './loader-C3DtD6HB.mjs';
 import 'package-directory';
 import 'yaml';
 import 'zod';
-import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
 
 /**
  * Attach the default action for the `aws whoami` command.
@@ -26,6 +25,22 @@ import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
  */
 function attachWhoamiDefaultAction(cli) {
     cli.action(async () => {
+        // Dynamic import: @aws-sdk/client-sts is an optional peer dependency.
+        // A static import would cause Node to fail at startup (even for -h)
+        // when the SDK is not installed in the consumer's project.
+        let GetCallerIdentityCommand;
+        let STSClient;
+        try {
+            const mod = await import('@aws-sdk/client-sts');
+            GetCallerIdentityCommand = mod.GetCallerIdentityCommand;
+            STSClient = mod.STSClient;
+        }
+        catch {
+            console.error('The aws whoami command requires @aws-sdk/client-sts.\n' +
+                'Install it with: npm install @aws-sdk/client-sts');
+            process.exitCode = 1;
+            return;
+        }
         // The AWS SDK default providers will read credentials from process.env,
         // which the aws parent has already populated.
         const client = new STSClient();

package/dist/chunks/{readMergedOptions-BT1C87_u.mjs → readMergedOptions-Bjl6rWXd.mjs}

@@ -737,6 +737,19 @@ const attachRootOptions = (program, defaults) => {
         program.addOption(lf);
         program.setOptionGroup(lf, GROUP);
     }
+    // Debug ON/OFF (dynamic)
+    {
+        const dOn = program
+            .createDynamicOption('--debug', (cfg) => `enable debug logging to stderr ${onOff(true, Boolean(cfg.debug))}`)
+            .conflicts('debugOff');
+        program.addOption(dOn);
+        program.setOptionGroup(dOn, GROUP);
+        const dOff = program
+            .createDynamicOption('--debug-off', (cfg) => `enable debug logging to stderr ${onOff(false, !cfg.debug)}`)
+            .conflicts('debug');
+        program.addOption(dOff);
+        program.setOptionGroup(dOff, GROUP);
+    }
     // Capture flag (no default display; static)
     {
         const opt = new Option('--capture', 'capture child process stdio for commands (tests/CI)');
@@ -1094,7 +1107,7 @@ const effectiveNs = (child) => {
 const isPromise = (v) => !!v && typeof v.then === 'function';
 function runInstall(parentCli, plugin) {
     // Create mount and run setup
-    const mount = parentCli.ns(plugin.ns);
+    const mount = parentCli.ns(plugin.ns, plugin.nsOptions);
     const setupRet = plugin.setup(mount);
     const pending = [];
     if (isPromise(setupRet))
@@ -1351,13 +1364,16 @@ class GetDotenvCli extends Command {
      * Convenience helper to create a namespaced subcommand with argument inference.
      * This mirrors Commander generics so downstream chaining stays fully typed.
      */
-    ns(name) {
+    ns(name, opts) {
         // Guard against same-level duplicate command names for clearer diagnostics.
         const exists = this.commands.some((c) => c.name() === name);
         if (exists) {
             throw new Error(`Duplicate command name: ${name}`);
         }
-        return this.command(name);
+        return this.command(name, {
+            ...(opts?.isDefault !== undefined ? { isDefault: opts.isDefault } : {}),
+            ...(opts?.hidden !== undefined ? { hidden: opts.hidden } : {}),
+        });
     }
     /**
      * Tag options added during the provided callback as 'app' for grouped help.

package/dist/chunks/{resolveCliOptions-BbfouWSK.mjs → resolveCliOptions-C0Jmb-6I.mjs}

@@ -1,4 +1,4 @@
-import { b as baseRootOptionDefaults, a as defaultsDeep } from './readMergedOptions-BT1C87_u.mjs';
+import { b as baseRootOptionDefaults, a as defaultsDeep } from './readMergedOptions-Bjl6rWXd.mjs';
 import 'radash';
 import 'node:buffer';
 import 'fs-extra';

package/dist/chunks/{types-BkQxnyZK.mjs → types-CcDLYiJ3.mjs}

@@ -1,4 +1,4 @@
-import { d as definePlugin } from './readMergedOptions-BT1C87_u.mjs';
+import { d as definePlugin } from './readMergedOptions-Bjl6rWXd.mjs';
 
 /**
  * Create a namespace-only parent plugin (a group command) for composing plugins

package/dist/cli.d.ts

@@ -484,7 +484,7 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
      * Create a namespaced child command with argument inference.
      * Mirrors Commander generics so downstream chaining remains fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;
@@ -525,6 +525,23 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
+/**
+ * Options for the `ns()` subcommand factory, forwarded to Commander's
+ * `command(name, opts)` second argument.
+ *
+ * @public
+ */
+interface NsOptions {
+    /**
+     * When true, this subcommand becomes the default: Commander routes
+     * unrecognized positional tokens to it when no explicit subcommand matches.
+     */
+    isDefault?: boolean;
+    /**
+     * When true, the subcommand is hidden from help output.
+     */
+    hidden?: boolean;
+}
 /**
  * Optional overrides for plugin composition.
  *
@@ -554,6 +571,11 @@ interface PluginChildEntry<TOptions extends GetDotenvOptions = GetDotenvOptions,
 interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
     /** Namespace (required): the command name where this plugin is mounted. */
     ns: string;
+    /**
+     * Options forwarded to the host's `ns()` call when creating the mount
+     * for this plugin (e.g. `{ isDefault: true }`).
+     */
+    nsOptions?: NsOptions;
     /**
      * Setup phase: register commands and wiring on the provided mount.
      * Runs parent → children (pre-order). Return nothing (void).
@@ -677,7 +699,7 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions,
      * Convenience helper to create a namespaced subcommand with argument inference.
      * This mirrors Commander generics so downstream chaining stays fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-export { c as createCli } from './chunks/createCli-CUPiFVdZ.mjs';
+export { c as createCli } from './chunks/createCli-BIG9hp19.mjs';
 import 'zod';
 import 'path';
 import './chunks/loader-C3DtD6HB.mjs';
@@ -13,22 +13,21 @@ import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
 import '@commander-js/extra-typings';
 import 'nanoid';
-import './chunks/readMergedOptions-BT1C87_u.mjs';
+import './chunks/readMergedOptions-Bjl6rWXd.mjs';
 import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import 'dotenv';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-BbfouWSK.mjs';
+import './chunks/resolveCliOptions-C0Jmb-6I.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
 import './chunks/spawnEnv-DvisqPiU.mjs';
-import './chunks/index-CNXekCQC.mjs';
-import '@aws-sdk/client-sts';
+import './chunks/index-DREvD42I.mjs';
 import './plugins-batch.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
 import 'globby';
 import 'os';
-import './chunks/index-DnG3N6yj.mjs';
+import './chunks/index-BAcAtESJ.mjs';
 import './plugins-init.mjs';
 import 'node:process';
 import 'readline/promises';

package/dist/cliHost.d.ts

@@ -500,7 +500,7 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
      * Create a namespaced child command with argument inference.
      * Mirrors Commander generics so downstream chaining remains fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;
@@ -541,6 +541,23 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
+/**
+ * Options for the `ns()` subcommand factory, forwarded to Commander's
+ * `command(name, opts)` second argument.
+ *
+ * @public
+ */
+interface NsOptions {
+    /**
+     * When true, this subcommand becomes the default: Commander routes
+     * unrecognized positional tokens to it when no explicit subcommand matches.
+     */
+    isDefault?: boolean;
+    /**
+     * When true, the subcommand is hidden from help output.
+     */
+    hidden?: boolean;
+}
 /**
  * Optional overrides for plugin composition.
  *
@@ -570,6 +587,11 @@ interface PluginChildEntry<TOptions extends GetDotenvOptions = GetDotenvOptions,
 interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
     /** Namespace (required): the command name where this plugin is mounted. */
     ns: string;
+    /**
+     * Options forwarded to the host's `ns()` call when creating the mount
+     * for this plugin (e.g. `{ isDefault: true }`).
+     */
+    nsOptions?: NsOptions;
     /**
      * Setup phase: register commands and wiring on the provided mount.
      * Runs parent → children (pre-order). Return nothing (void).
@@ -867,7 +889,7 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions,
      * Convenience helper to create a namespaced subcommand with argument inference.
      * This mirrors Commander generics so downstream chaining stays fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;
@@ -1147,4 +1169,4 @@ declare const resolveCliOptions: <T extends ResolveCliOptionsShape>(rawCliOption
 declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: ProcessEnv) => NodeJS.ProcessEnv;
 
 export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, describeConfigKeyListDefaults, describeDefault, ensureForce, getRootCommand, groupPlugins, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, shouldCapture, stripOne, toHelpConfig };
-export type { BrandOptions, DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, GroupPluginsOptions, InferPluginConfig, PluginChildEntry, PluginFlattenedEntry, PluginNamespaceOverride, PluginWithInstanceHelpers, ResolveAndLoadOptions, ResolveCliOptionsResult, ResolvedHelpConfig, RootOptionsShape, RunCommandOptions, RunCommandResultOptions, ScriptDef, Scripts, ScriptsTable };
+export type { BrandOptions, DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, GroupPluginsOptions, InferPluginConfig, NsOptions, PluginChildEntry, PluginFlattenedEntry, PluginNamespaceOverride, PluginWithInstanceHelpers, ResolveAndLoadOptions, ResolveCliOptionsResult, ResolvedHelpConfig, RootOptionsShape, RunCommandOptions, RunCommandResultOptions, ScriptDef, Scripts, ScriptsTable };

package/dist/cliHost.mjs

@@ -1,7 +1,7 @@
-export { G as GetDotenvCli, d as definePlugin, r as readMergedOptions } from './chunks/readMergedOptions-BT1C87_u.mjs';
+export { G as GetDotenvCli, d as definePlugin, r as readMergedOptions } from './chunks/readMergedOptions-Bjl6rWXd.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-BbfouWSK.mjs';
-export { d as defineScripts, g as groupPlugins } from './chunks/types-BkQxnyZK.mjs';
+export { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './chunks/resolveCliOptions-C0Jmb-6I.mjs';
+export { d as defineScripts, g as groupPlugins } from './chunks/types-CcDLYiJ3.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';

package/dist/getdotenv.cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { c as createCli } from './chunks/createCli-CUPiFVdZ.mjs';
+import { c as createCli } from './chunks/createCli-BIG9hp19.mjs';
 import 'zod';
 import 'path';
 import './chunks/loader-C3DtD6HB.mjs';
@@ -14,22 +14,21 @@ import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
 import '@commander-js/extra-typings';
 import 'nanoid';
-import './chunks/readMergedOptions-BT1C87_u.mjs';
+import './chunks/readMergedOptions-Bjl6rWXd.mjs';
 import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import 'dotenv';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-BbfouWSK.mjs';
+import './chunks/resolveCliOptions-C0Jmb-6I.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
 import './chunks/spawnEnv-DvisqPiU.mjs';
-import './chunks/index-CNXekCQC.mjs';
-import '@aws-sdk/client-sts';
+import './chunks/index-DREvD42I.mjs';
 import './plugins-batch.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
 import 'globby';
 import 'os';
-import './chunks/index-DnG3N6yj.mjs';
+import './chunks/index-BAcAtESJ.mjs';
 import './plugins-init.mjs';
 import 'node:process';
 import 'readline/promises';

package/dist/index.d.ts

@@ -652,7 +652,7 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
      * Create a namespaced child command with argument inference.
      * Mirrors Commander generics so downstream chaining remains fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;
@@ -693,6 +693,23 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
+/**
+ * Options for the `ns()` subcommand factory, forwarded to Commander's
+ * `command(name, opts)` second argument.
+ *
+ * @public
+ */
+interface NsOptions {
+    /**
+     * When true, this subcommand becomes the default: Commander routes
+     * unrecognized positional tokens to it when no explicit subcommand matches.
+     */
+    isDefault?: boolean;
+    /**
+     * When true, the subcommand is hidden from help output.
+     */
+    hidden?: boolean;
+}
 /**
  * Optional overrides for plugin composition.
  *
@@ -722,6 +739,11 @@ interface PluginChildEntry<TOptions extends GetDotenvOptions = GetDotenvOptions,
 interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
     /** Namespace (required): the command name where this plugin is mounted. */
     ns: string;
+    /**
+     * Options forwarded to the host's `ns()` call when creating the mount
+     * for this plugin (e.g. `{ isDefault: true }`).
+     */
+    nsOptions?: NsOptions;
     /**
      * Setup phase: register commands and wiring on the provided mount.
      * Runs parent → children (pre-order). Return nothing (void).
@@ -916,7 +938,7 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions,
      * Convenience helper to create a namespaced subcommand with argument inference.
      * This mirrors Commander generics so downstream chaining stays fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;

package/dist/index.mjs

@@ -1,8 +1,8 @@
-export { c as createCli } from './chunks/createCli-CUPiFVdZ.mjs';
-import { e as resolveGetDotenvOptions, w as writeDotenvFile } from './chunks/readMergedOptions-BT1C87_u.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-BT1C87_u.mjs';
+export { c as createCli } from './chunks/createCli-BIG9hp19.mjs';
+import { e as resolveGetDotenvOptions, w as writeDotenvFile } from './chunks/readMergedOptions-Bjl6rWXd.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-Bjl6rWXd.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-BkQxnyZK.mjs';
+export { d as defineScripts, g as groupPlugins } from './chunks/types-CcDLYiJ3.mjs';
 import { omit, pick } from 'radash';
 import { Buffer } from 'node:buffer';
 export { l as loadModuleDefault } from './chunks/loadModuleDefault-Dj8B3Stt.mjs';
@@ -10,8 +10,8 @@ import { InvalidArgumentError } from '@commander-js/extra-typings';
 import 'zod';
 import { nanoid } from 'nanoid';
 import path$1 from 'path';
-import { r as redactObject, m as maybeWarnEntropy } from './chunks/index-DnG3N6yj.mjs';
-export { a as redactDisplay, t as traceChildEnv } from './chunks/index-DnG3N6yj.mjs';
+import { r as redactObject, m as maybeWarnEntropy } from './chunks/index-BAcAtESJ.mjs';
+export { a as redactDisplay, t as traceChildEnv } from './chunks/index-BAcAtESJ.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';
@@ -24,11 +24,10 @@ import 'package-directory';
 import 'yaml';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-BbfouWSK.mjs';
+import './chunks/resolveCliOptions-C0Jmb-6I.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
-import './chunks/index-CNXekCQC.mjs';
-import '@aws-sdk/client-sts';
+import './chunks/index-DREvD42I.mjs';
 import './plugins-batch.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
 import 'globby';

package/dist/plugins-aws.d.ts

@@ -378,7 +378,7 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
      * Create a namespaced child command with argument inference.
      * Mirrors Commander generics so downstream chaining remains fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;
@@ -419,6 +419,23 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
+/**
+ * Options for the `ns()` subcommand factory, forwarded to Commander's
+ * `command(name, opts)` second argument.
+ *
+ * @public
+ */
+interface NsOptions {
+    /**
+     * When true, this subcommand becomes the default: Commander routes
+     * unrecognized positional tokens to it when no explicit subcommand matches.
+     */
+    isDefault?: boolean;
+    /**
+     * When true, the subcommand is hidden from help output.
+     */
+    hidden?: boolean;
+}
 /**
  * Optional overrides for plugin composition.
  *
@@ -448,6 +465,11 @@ interface PluginChildEntry<TOptions extends GetDotenvOptions = GetDotenvOptions,
 interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
     /** Namespace (required): the command name where this plugin is mounted. */
     ns: string;
+    /**
+     * Options forwarded to the host's `ns()` call when creating the mount
+     * for this plugin (e.g. `{ isDefault: true }`).
+     */
+    nsOptions?: NsOptions;
     /**
      * Setup phase: register commands and wiring on the provided mount.
      * Runs parent → children (pre-order). Return nothing (void).

package/dist/plugins-aws.mjs

@@ -1,4 +1,4 @@
-import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-BT1C87_u.mjs';
+import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-Bjl6rWXd.mjs';
 import 'execa';
 import { isObject } from 'radash';
 import 'node:buffer';

package/dist/plugins-batch.d.ts

@@ -378,7 +378,7 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
      * Create a namespaced child command with argument inference.
      * Mirrors Commander generics so downstream chaining remains fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;
@@ -419,6 +419,23 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
+/**
+ * Options for the `ns()` subcommand factory, forwarded to Commander's
+ * `command(name, opts)` second argument.
+ *
+ * @public
+ */
+interface NsOptions {
+    /**
+     * When true, this subcommand becomes the default: Commander routes
+     * unrecognized positional tokens to it when no explicit subcommand matches.
+     */
+    isDefault?: boolean;
+    /**
+     * When true, the subcommand is hidden from help output.
+     */
+    hidden?: boolean;
+}
 /**
  * Optional overrides for plugin composition.
  *
@@ -448,6 +465,11 @@ interface PluginChildEntry<TOptions extends GetDotenvOptions = GetDotenvOptions,
 interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
     /** Namespace (required): the command name where this plugin is mounted. */
     ns: string;
+    /**
+     * Options forwarded to the host's `ns()` call when creating the mount
+     * for this plugin (e.g. `{ isDefault: true }`).
+     */
+    nsOptions?: NsOptions;
     /**
      * Setup phase: register commands and wiring on the provided mount.
      * Runs parent → children (pre-order). Return nothing (void).

package/dist/plugins-batch.mjs

@@ -1,4 +1,4 @@
-import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-BT1C87_u.mjs';
+import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-Bjl6rWXd.mjs';
 import 'execa';
 import 'radash';
 import 'node:buffer';

package/dist/plugins-cmd.d.ts

@@ -378,7 +378,7 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
      * Create a namespaced child command with argument inference.
      * Mirrors Commander generics so downstream chaining remains fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;
@@ -419,6 +419,23 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
+/**
+ * Options for the `ns()` subcommand factory, forwarded to Commander's
+ * `command(name, opts)` second argument.
+ *
+ * @public
+ */
+interface NsOptions {
+    /**
+     * When true, this subcommand becomes the default: Commander routes
+     * unrecognized positional tokens to it when no explicit subcommand matches.
+     */
+    isDefault?: boolean;
+    /**
+     * When true, the subcommand is hidden from help output.
+     */
+    hidden?: boolean;
+}
 /**
  * Optional overrides for plugin composition.
  *
@@ -448,6 +465,11 @@ interface PluginChildEntry<TOptions extends GetDotenvOptions = GetDotenvOptions,
 interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
     /** Namespace (required): the command name where this plugin is mounted. */
     ns: string;
+    /**
+     * Options forwarded to the host's `ns()` call when creating the mount
+     * for this plugin (e.g. `{ isDefault: true }`).
+     */
+    nsOptions?: NsOptions;
     /**
      * Setup phase: register commands and wiring on the provided mount.
      * Runs parent → children (pre-order). Return nothing (void).

package/dist/plugins-cmd.mjs

@@ -1,5 +1,5 @@
 import 'radash';
-import './chunks/readMergedOptions-BT1C87_u.mjs';
+import './chunks/readMergedOptions-Bjl6rWXd.mjs';
 import 'execa';
 import 'node:buffer';
 import 'fs-extra';
@@ -14,9 +14,9 @@ import './chunks/loader-C3DtD6HB.mjs';
 import 'package-directory';
 import 'yaml';
 import 'zod';
-export { c as cmdPlugin } from './chunks/index-DnG3N6yj.mjs';
+export { c as cmdPlugin } from './chunks/index-BAcAtESJ.mjs';
 import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import './chunks/spawnEnv-DvisqPiU.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
-import './chunks/resolveCliOptions-BbfouWSK.mjs';
+import './chunks/resolveCliOptions-C0Jmb-6I.mjs';

package/dist/plugins-init.d.ts

@@ -378,7 +378,7 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
      * Create a namespaced child command with argument inference.
      * Mirrors Commander generics so downstream chaining remains fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;
@@ -419,6 +419,23 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
+/**
+ * Options for the `ns()` subcommand factory, forwarded to Commander's
+ * `command(name, opts)` second argument.
+ *
+ * @public
+ */
+interface NsOptions {
+    /**
+     * When true, this subcommand becomes the default: Commander routes
+     * unrecognized positional tokens to it when no explicit subcommand matches.
+     */
+    isDefault?: boolean;
+    /**
+     * When true, the subcommand is hidden from help output.
+     */
+    hidden?: boolean;
+}
 /**
  * Optional overrides for plugin composition.
  *
@@ -448,6 +465,11 @@ interface PluginChildEntry<TOptions extends GetDotenvOptions = GetDotenvOptions,
 interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
     /** Namespace (required): the command name where this plugin is mounted. */
     ns: string;
+    /**
+     * Options forwarded to the host's `ns()` call when creating the mount
+     * for this plugin (e.g. `{ isDefault: true }`).
+     */
+    nsOptions?: NsOptions;
     /**
      * Setup phase: register commands and wiring on the provided mount.
      * Runs parent → children (pre-order). Return nothing (void).

package/dist/plugins-init.mjs

@@ -1,4 +1,4 @@
-import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-BT1C87_u.mjs';
+import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-Bjl6rWXd.mjs';
 import 'execa';
 import 'radash';
 import 'node:buffer';

package/dist/plugins.d.ts

@@ -378,7 +378,7 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
      * Create a namespaced child command with argument inference.
      * Mirrors Commander generics so downstream chaining remains fully typed.
      */
-    ns<Usage extends string>(name: Usage): GetDotenvCliPublic<TOptions, [
+    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
         ...TArgs,
         ...InferCommandArguments<Usage>
     ], {}, TOpts & TGlobal>;
@@ -419,6 +419,23 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
+/**
+ * Options for the `ns()` subcommand factory, forwarded to Commander's
+ * `command(name, opts)` second argument.
+ *
+ * @public
+ */
+interface NsOptions {
+    /**
+     * When true, this subcommand becomes the default: Commander routes
+     * unrecognized positional tokens to it when no explicit subcommand matches.
+     */
+    isDefault?: boolean;
+    /**
+     * When true, the subcommand is hidden from help output.
+     */
+    hidden?: boolean;
+}
 /**
  * Optional overrides for plugin composition.
  *
@@ -448,6 +465,11 @@ interface PluginChildEntry<TOptions extends GetDotenvOptions = GetDotenvOptions,
 interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
     /** Namespace (required): the command name where this plugin is mounted. */
     ns: string;
+    /**
+     * Options forwarded to the host's `ns()` call when creating the mount
+     * for this plugin (e.g. `{ isDefault: true }`).
+     */
+    nsOptions?: NsOptions;
     /**
      * Setup phase: register commands and wiring on the provided mount.
      * Runs parent → children (pre-order). Return nothing (void).

package/dist/plugins.mjs

@@ -1,9 +1,9 @@
 export { awsPlugin, getAwsRegion } from './plugins-aws.mjs';
-export { a as awsWhoamiPlugin } from './chunks/index-CNXekCQC.mjs';
+export { a as awsWhoamiPlugin } from './chunks/index-DREvD42I.mjs';
 export { batchPlugin } from './plugins-batch.mjs';
-export { c as cmdPlugin } from './chunks/index-DnG3N6yj.mjs';
+export { c as cmdPlugin } from './chunks/index-BAcAtESJ.mjs';
 export { initPlugin } from './plugins-init.mjs';
-import './chunks/readMergedOptions-BT1C87_u.mjs';
+import './chunks/readMergedOptions-Bjl6rWXd.mjs';
 import 'zod';
 import '@commander-js/extra-typings';
 import './chunks/readDotenvCascade-CfFPgLCp.mjs';
@@ -22,11 +22,10 @@ import 'package-directory';
 import 'yaml';
 import 'execa';
 import './chunks/spawnEnv-DvisqPiU.mjs';
-import '@aws-sdk/client-sts';
 import './chunks/invoke-DuRPU1oC.mjs';
 import 'globby';
 import 'os';
-import './chunks/resolveCliOptions-BbfouWSK.mjs';
+import './chunks/resolveCliOptions-C0Jmb-6I.mjs';
 import 'node:process';
 import 'readline/promises';
 import 'node:url';

package/package.json

@@ -221,5 +221,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "7.0.8"
+  "version": "7.0.10"
 }