@karmaniverous/get-dotenv 4.6.0-0 → 5.0.0-1

package/dist/plugins-init.d.ts

@@ -0,0 +1,180 @@
+import { ZodType } from 'zod';
+import { Command } from 'commander';
+
+/**
+ * A minimal representation of an environment key/value mapping.
+ * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
+/**
+ * Dynamic variable function signature. Receives the current expanded variables
+ * 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 GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
+type Logger = Record<string, (...args: unknown[]) => void> | typeof console;
+/**
+ * Options passed programmatically to `getDotenv`.
+ */
+interface GetDotenvOptions {
+    /**
+     * default target environment (used if `env` is not provided)
+     */
+    defaultEnv?: string;
+    /**
+     * token indicating a dotenv file
+     */
+    dotenvToken: string;
+    /**
+     * path to JS/TS module default-exporting an object keyed to dynamic variable functions
+     */
+    dynamicPath?: string;
+    /**
+     * Programmatic dynamic variables map. When provided, this takes precedence
+     * over {@link GetDotenvOptions.dynamicPath}.
+     */
+    dynamic?: GetDotenvDynamic;
+    /**
+     * target environment
+     */
+    env?: string;
+    /**
+     * exclude dynamic variables from loading
+     */
+    excludeDynamic?: boolean;
+    /**
+     * exclude environment-specific variables from loading
+     */
+    excludeEnv?: boolean;
+    /**
+     * exclude global variables from loading
+     */
+    excludeGlobal?: boolean;
+    /**
+     * exclude private variables from loading
+     */
+    excludePrivate?: boolean;
+    /**
+     * exclude public variables from loading
+     */
+    excludePublic?: boolean;
+    /**
+     * load dotenv variables to `process.env`
+     */
+    loadProcess?: boolean;
+    /**
+     * log loaded dotenv variables to `logger`
+     */
+    log?: boolean;
+    /**
+     * logger object (defaults to console)
+     */
+    logger?: Logger;
+    /**
+     * if populated, writes consolidated dotenv file to this path (follows dotenvExpand rules)
+     */
+    outputPath?: string;
+    /**
+     * array of input directory paths
+     */
+    paths?: string[];
+    /**
+     * filename token indicating private variables
+     */
+    privateToken?: string;
+    /**
+     * explicit variables to include
+     */
+    vars?: ProcessEnv;
+    /**
+     * Reserved: config loader flag (no-op).
+     * The plugin-first host and generator paths already use the config
+     * loader/overlay pipeline unconditionally (no-op when no config files
+     * are present). This flag is accepted for forward compatibility but
+     * currently has no effect.
+     */
+    useConfigLoader?: boolean;
+}
+
+/** * Per-invocation context shared with plugins and actions. */
+type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
+    optionsResolved: TOptions;
+    dotenv: ProcessEnv;
+    plugins?: Record<string, unknown>;
+    pluginConfigs?: Record<string, unknown>;
+};
+/**
+ * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
+ *
+ * Responsibilities:
+ * - Resolve options strictly and compute dotenv context (resolveAndLoad).
+ * - Expose a stable accessor for the current context (getCtx).
+ * - Provide a namespacing helper (ns).
+ * - Support composable plugins with parent → children install and afterResolve.
+ *
+ * NOTE: This host is additive and does not alter the legacy CLI.
+ */
+declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
+    /** Registered top-level plugins (composition happens via .use()) */
+    private _plugins;
+    /** One-time installation guard */
+    private _installed;
+    constructor(alias?: string);
+    /**
+     * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
+     */
+    resolveAndLoad(customOptions?: Partial<TOptions>): Promise<GetDotenvCliCtx<TOptions>>;
+    /**
+     * Retrieve the current invocation context (if any).
+     */
+    getCtx(): GetDotenvCliCtx<TOptions> | undefined;
+    /**   * Convenience helper to create a namespaced subcommand.
+     */
+    ns(name: string): Command;
+    /**
+     * Register a plugin for installation (parent level).
+     * Installation occurs on first resolveAndLoad() (or explicit install()).
+     */
+    use(plugin: GetDotenvCliPlugin): this;
+    /**
+     * Install all registered plugins in parent → children (pre-order).
+     * Runs only once per CLI instance.
+     */
+    install(): Promise<void>;
+    /**
+     * Run afterResolve hooks for all plugins (parent → children).
+     */
+    private _runAfterResolve;
+}
+
+/** Public plugin contract used by the GetDotenv CLI host. */ interface GetDotenvCliPlugin {
+    id?: string /**
+     * Setup phase: register commands and wiring on the provided CLI instance.   * Runs parent → children (pre-order).
+     */;
+    setup: (cli: GetDotenvCli) => void | Promise<void>;
+    /**
+     * After the dotenv context is resolved, initialize any clients/secrets
+     * or attach per-plugin state under ctx.plugins (by convention).
+     * Runs parent → children (pre-order).
+     */
+    afterResolve?: (cli: GetDotenvCli, ctx: GetDotenvCliCtx) => void | Promise<void>;
+    /**
+     * Optional Zod schema for this plugin's config slice (from config.plugins[id]).
+     * When provided, the host validates the merged config under the guarded loader path.
+     */
+    configSchema?: ZodType;
+    /**
+     * Compositional children. Installed after the parent per pre-order.
+     */ children: GetDotenvCliPlugin[];
+    /**
+     * Compose a child plugin. Returns the parent to enable chaining.
+     */
+    use: (child: GetDotenvCliPlugin) => GetDotenvCliPlugin;
+}
+
+type InitPluginOptions = {
+    logger?: Logger;
+};
+declare const initPlugin: (opts?: InitPluginOptions) => GetDotenvCliPlugin;
+
+export { initPlugin };
+export type { InitPluginOptions };

package/dist/plugins-init.mjs

@@ -0,0 +1,280 @@
+import { stdin, stdout } from 'node:process';
+import fs from 'fs-extra';
+import path from 'path';
+import { createInterface } from 'readline/promises';
+
+/**
+ * Define a GetDotenv CLI plugin with compositional helpers.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
+ */
+const definePlugin = (spec) => {
+    const { children = [], ...rest } = spec;
+    const plugin = {
+        ...rest,
+        children: [...children],
+        use(child) {
+            this.children.push(child);
+            return this;
+        },
+    };
+    return plugin;
+};
+
+const ensureDir = async (p) => {
+    await fs.ensureDir(p);
+    return p;
+};
+const writeFile = async (dest, data) => {
+    await ensureDir(path.dirname(dest));
+    await fs.writeFile(dest, data, 'utf-8');
+};
+const copyTextFile = async (src, dest, substitutions) => {
+    const contents = await fs.readFile(src, 'utf-8');
+    const out = substitutions && Object.keys(substitutions).length > 0
+        ? Object.entries(substitutions).reduce((acc, [k, v]) => acc.split(k).join(v), contents)
+        : contents;
+    await writeFile(dest, out);
+};
+/**
+ * Ensure a set of lines exist (exact match) in a file. Creates the file
+ * when missing. Returns whether it was created or changed.
+ */
+const ensureLines = async (filePath, lines) => {
+    const exists = await fs.pathExists(filePath);
+    const current = exists ? await fs.readFile(filePath, 'utf-8') : '';
+    const curLines = current.split(/\r?\n/);
+    const have = new Set(curLines.filter((l) => l.length > 0));
+    let mutated = false;
+    for (const l of lines) {
+        if (!have.has(l)) {
+            curLines.push(l);
+            have.add(l);
+            mutated = true;
+        }
+    }
+    // Normalize to LF and ensure trailing newline
+    const next = curLines.filter((l) => l.length > 0).join('\n') + '\n';
+    if (!exists) {
+        await writeFile(filePath, next);
+        return { created: true, changed: true };
+    }
+    if (mutated) {
+        await fs.writeFile(filePath, next, 'utf-8');
+        return { created: false, changed: true };
+    }
+    return { created: false, changed: false };
+};
+
+// Templates root used by the scaffolder
+const TEMPLATES_ROOT = path.resolve('templates');
+
+const planConfigCopies = ({ format, withLocal, destRoot, }) => {
+    const copies = [];
+    if (format === 'json') {
+        copies.push({
+            src: path.join(TEMPLATES_ROOT, 'config', 'json', 'public', 'getdotenv.config.json'),
+            dest: path.join(destRoot, 'getdotenv.config.json'),
+        });
+        if (withLocal) {
+            copies.push({
+                src: path.join(TEMPLATES_ROOT, 'config', 'json', 'local', 'getdotenv.config.local.json'),
+                dest: path.join(destRoot, 'getdotenv.config.local.json'),
+            });
+        }
+    }
+    else if (format === 'yaml') {
+        copies.push({
+            src: path.join(TEMPLATES_ROOT, 'config', 'yaml', 'public', 'getdotenv.config.yaml'),
+            dest: path.join(destRoot, 'getdotenv.config.yaml'),
+        });
+        if (withLocal) {
+            copies.push({
+                src: path.join(TEMPLATES_ROOT, 'config', 'yaml', 'local', 'getdotenv.config.local.yaml'),
+                dest: path.join(destRoot, 'getdotenv.config.local.yaml'),
+            });
+        }
+    }
+    else if (format === 'js') {
+        copies.push({
+            src: path.join(TEMPLATES_ROOT, 'config', 'js', 'getdotenv.config.js'),
+            dest: path.join(destRoot, 'getdotenv.config.js'),
+        });
+    }
+    else {
+        copies.push({
+            src: path.join(TEMPLATES_ROOT, 'config', 'ts', 'getdotenv.config.ts'),
+            dest: path.join(destRoot, 'getdotenv.config.ts'),
+        });
+    }
+    return copies;
+};
+const planCliCopies = ({ cliName, destRoot, }) => {
+    const subs = { __CLI_NAME__: cliName };
+    const base = path.join(destRoot, 'src', 'cli', cliName);
+    return [
+        {
+            src: path.join(TEMPLATES_ROOT, 'cli', 'ts', 'index.ts'),
+            dest: path.join(base, 'index.ts'),
+            subs,
+        },
+        {
+            src: path.join(TEMPLATES_ROOT, 'cli', 'ts', 'plugins', 'hello.ts'),
+            dest: path.join(base, 'plugins', 'hello.ts'),
+            subs,
+        },
+    ];
+};
+
+/**
+ * Determine whether the current environment should be treated as non-interactive.
+ * CI heuristics include: CI, GITHUB_ACTIONS, BUILDKITE, TEAMCITY_VERSION, TF_BUILD.
+ */
+const isNonInteractive = () => {
+    const ciLike = process.env.CI ||
+        process.env.GITHUB_ACTIONS ||
+        process.env.BUILDKITE ||
+        process.env.TEAMCITY_VERSION ||
+        process.env.TF_BUILD;
+    return Boolean(ciLike) || !(stdin.isTTY && stdout.isTTY);
+};
+const promptDecision = async (filePath, logger, rl) => {
+    logger.log(`File exists: ${filePath}\nChoose: [o]verwrite, [e]xample, [s]kip, [O]verwrite All, [E]xample All, [S]kip All`);
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+        const a = (await rl.question('> ')).trim();
+        const valid = ['o', 'e', 's', 'O', 'E', 'S'];
+        if (valid.includes(a))
+            return a;
+        logger.log('Please enter one of: o e s O E S');
+    }
+};
+
+/**
+ * Requirements: Init scaffolding plugin with collision flow and CI detection.
+ * Note: Large file scheduled for decomposition; tracked in stan.todo.md.
+ */
+const initPlugin = (opts = {}) => definePlugin({
+    id: 'init',
+    setup(cli) {
+        const logger = opts.logger ?? console;
+        const cmd = cli
+            .ns('init')
+            .description('Scaffold getdotenv config files and a host-based CLI skeleton.')
+            .argument('[dest]', 'destination path (default: ./)', '.')
+            .option('--config-format <format>', 'config format: json|yaml|js|ts', 'json')
+            .option('--with-local', 'include .local config variant')
+            .option('--dynamic', 'include dynamic examples (JS/TS configs)')
+            .option('--cli-name <string>', 'CLI name for skeleton and tokens')
+            .option('--force', 'overwrite all existing files')
+            .option('--yes', 'skip all collisions (no overwrite)')
+            .action(async (destArg) => {
+            // Read options directly from the captured command instance.
+            // Cast to a plain record to satisfy exact-optional and lint safety.
+            const o = cmd.opts() ?? {};
+            const destRel = typeof destArg === 'string' && destArg.length > 0 ? destArg : '.';
+            const cwd = process.cwd();
+            const destRoot = path.resolve(cwd, destRel);
+            const formatInput = o.configFormat;
+            const formatRaw = typeof formatInput === 'string'
+                ? formatInput.toLowerCase()
+                : 'json';
+            const format = (['json', 'yaml', 'js', 'ts'].includes(formatRaw)
+                ? formatRaw
+                : 'json');
+            const withLocal = !!o.withLocal;
+            // dynamic flag reserved for future template variants; present for UX compatibility
+            void o.dynamic;
+            // CLI name default: --cli-name | basename(dest) | 'mycli'
+            const cliName = (typeof o.cliName === 'string' && o.cliName.length > 0
+                ? o.cliName
+                : path.basename(destRoot) || 'mycli') || 'mycli';
+            // Precedence: --force > --yes > auto-detect(non-interactive => yes)
+            const force = !!o.force;
+            const yes = !!o.yes || (!force && isNonInteractive());
+            // Build copy plan
+            const cfgCopies = planConfigCopies({ format, withLocal, destRoot });
+            const cliCopies = planCliCopies({ cliName, destRoot });
+            const copies = [...cfgCopies, ...cliCopies];
+            // Interactive state
+            let globalDecision;
+            const rl = createInterface({ input: stdin, output: stdout });
+            try {
+                for (const item of copies) {
+                    const exists = await fs.pathExists(item.dest);
+                    if (!exists) {
+                        const subs = item.subs ?? {};
+                        await copyTextFile(item.src, item.dest, subs);
+                        logger.log(`Created ${path.relative(cwd, item.dest)}`);
+                        continue;
+                    }
+                    // Collision
+                    if (force) {
+                        const subs = item.subs ?? {};
+                        await copyTextFile(item.src, item.dest, subs);
+                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
+                        continue;
+                    }
+                    if (yes) {
+                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
+                        continue;
+                    }
+                    let decision = globalDecision;
+                    if (!decision) {
+                        const a = await promptDecision(item.dest, logger, rl);
+                        if (a === 'O') {
+                            globalDecision = 'overwrite';
+                            decision = 'overwrite';
+                        }
+                        else if (a === 'E') {
+                            globalDecision = 'example';
+                            decision = 'example';
+                        }
+                        else if (a === 'S') {
+                            globalDecision = 'skip';
+                            decision = 'skip';
+                        }
+                        else {
+                            decision =
+                                a === 'o' ? 'overwrite' : a === 'e' ? 'example' : 'skip';
+                        }
+                    }
+                    if (decision === 'overwrite') {
+                        const subs = item.subs ?? {};
+                        await copyTextFile(item.src, item.dest, subs);
+                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
+                    }
+                    else if (decision === 'example') {
+                        const destEx = `${item.dest}.example`;
+                        const subs = item.subs ?? {};
+                        await copyTextFile(item.src, destEx, subs);
+                        logger.log(`Wrote example ${path.relative(cwd, destEx)}`);
+                    }
+                    else {
+                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
+                    }
+                }
+                // Ensure .gitignore includes local config patterns.
+                const giPath = path.join(destRoot, '.gitignore');
+                const { created, changed } = await ensureLines(giPath, [
+                    'getdotenv.config.local.*',
+                    '*.local',
+                ]);
+                if (created) {
+                    logger.log(`Created ${path.relative(cwd, giPath)}`);
+                }
+                else if (changed) {
+                    logger.log(`Updated ${path.relative(cwd, giPath)}`);
+                }
+            }
+            finally {
+                rl.close();
+            }
+        });
+    },
+});
+
+export { initPlugin };

package/getdotenv.config.json

@@ -0,0 +1,19 @@
+{
+  "//": "Packaged root defaults for get-dotenv (lowest precedence).",
+  "dotenvToken": ".env",
+  "privateToken": "local",
+  "paths": "./",
+  "loadProcess": true,
+  "shell": true,
+  "scripts": {
+    "git-status": {
+      "cmd": "git branch --show-current && git status -s -u",
+      "shell": true
+    }
+  },
+  "excludeDynamic": false,
+  "excludeEnv": false,
+  "excludeGlobal": false,
+  "excludePrivate": false,
+  "excludePublic": false
+}

package/package.json

@@ -16,15 +16,17 @@
     "commander": "^14.0.1",
     "dotenv": "^17.2.2",
     "execa": "^9.6.0",
-    "fs-extra": "^11.3.1",
+    "fs-extra": "^11.3.2",
     "globby": "^14",
     "nanoid": "^5.1.5",
-    "package-directory": "^8.1.0"
+    "package-directory": "^8.1.0",
+    "yaml": "^2.8.1",
+    "zod": "^4.1.9"
   },
   "description": "Process dotenv files in an arbitrary location & optionally populate environment variables.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.49.1",
-    "@eslint/js": "^9.35.0",
+    "@dotenvx/dotenvx": "^1.50.1",
+    "@eslint/js": "^9.36.0",
     "@rollup/plugin-alias": "^5.1.1",
     "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-json": "^6.1.0",
@@ -32,25 +34,26 @@
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^22",
+    "@vitest/eslint-plugin": "^1.3.6",
     "@vitest/coverage-v8": "^3.2.4",
     "auto-changelog": "^2.5.0",
-    "esbuild": "^0.23.0",
-    "eslint": "^9.35.0",
+    "esbuild": "^0.25.10",
+    "eslint": "^9.36.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsonc": "^2.20.1",
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-tsdoc": "^0.4.0",
-    "eslint-plugin-vitest": "^0.5.4",
-    "fs-extra": "^11.3.1",
+    "fs-extra": "^11.3.2",
     "globals": "^16.4.0",
     "jsonc-eslint-parser": "^2.4.0",
     "knip": "^5.63.1",
-    "lefthook": "^1.13.0",
+    "npm-packlist": "^10.0.1",
+    "lefthook": "^1.13.1",
     "prettier": "^3.6.2",
-    "release-it": "^19.0.4",
+    "release-it": "^19.0.5",
     "rimraf": "^6.0.1",
-    "rollup": "^4.50.2",
+    "rollup": "^4.52.0",
     "rollup-plugin-dts": "^6.2.3",
     "tslib": "^2.8.1",
     "tsx": "^4.20.5",
@@ -58,12 +61,12 @@
     "typedoc-plugin-mdn-links": "^5.0.9",
     "typedoc-plugin-replace-text": "^4.2.0",
     "typescript": "^5.9.2",
-    "typescript-eslint": "^8.43.0",
+    "typescript-eslint": "^8.44.0",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4"
   },
   "engines": {
-    "node": ">=22.19"
+    "node": ">=20"
   },
   "exports": {
     ".": {
@@ -75,10 +78,72 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./cliHost": {
+      "import": {
+        "types": "./dist/cliHost.d.mts",
+        "default": "./dist/cliHost.mjs"
+      },
+      "require": {
+        "types": "./dist/cliHost.d.cts",
+        "default": "./dist/cliHost.cjs"
+      }
+    },
+    "./plugins/aws": {
+      "import": {
+        "types": "./dist/plugins-aws.d.mts",
+        "default": "./dist/plugins-aws.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins-aws.d.cts",
+        "default": "./dist/plugins-aws.cjs"
+      }
+    },
+    "./plugins/batch": {
+      "import": {
+        "types": "./dist/plugins-batch.d.mts",
+        "default": "./dist/plugins-batch.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins-batch.d.cts",
+        "default": "./dist/plugins-batch.cjs"
+      }
+    },
+    "./plugins/init": {
+      "import": {
+        "types": "./dist/plugins-init.d.mts",
+        "default": "./dist/plugins-init.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins-init.d.cts",
+        "default": "./dist/plugins-init.cjs"
+      }
+    },
+    "./config": {
+      "import": {
+        "types": "./dist/config.d.mts",
+        "default": "./dist/config.mjs"
+      },
+      "require": {
+        "types": "./dist/config.d.cts",
+        "default": "./dist/config.cjs"
+      }
+    },
+    "./env/overlay": {
+      "import": {
+        "types": "./dist/env-overlay.d.mts",
+        "default": "./dist/env-overlay.mjs"
+      },
+      "require": {
+        "types": "./dist/env-overlay.d.cts",
+        "default": "./dist/env-overlay.cjs"
+      }
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "getdotenv.config.json",
+    "templates"
   ],
   "homepage": "https://github.com/karmaniverous/get-dotenv#readme",
   "keywords": [
@@ -120,7 +185,9 @@
       "after:init": [
         "npm run lint",
         "npm run test",
-        "npm run build"
+        "npm run build",
+        "npm run verify:package",
+        "npm run verify:tarball"
       ],
       "after:release": [
         "git switch -c release/${version}",
@@ -142,6 +209,7 @@
     "cli:dist": "node dist/getdotenv.cli.mjs",
     "changelog": "auto-changelog",
     "docs": "typedoc",
+    "pack:dry": "npm pack --dry-run",
     "knip": "knip",
     "lint": "eslint . eslint.config.ts",
     "lint:fix": "eslint --fix . eslint.config.ts",
@@ -149,9 +217,12 @@
     "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
     "stan:docs": "typedoc --emit none",
     "test": "vitest run --coverage",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify:package": "node tools/verify-package.js",
+    "verify:smoke": "node tools/smoke.js",
+    "verify:tarball": "node tools/verify-tarball.js"
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "4.6.0-0"
+  "version": "5.0.0-1"
 }

package/templates/cli/ts/index.ts

@@ -0,0 +1,9 @@
+import { GetDotenvCli } from '@karmaniverous/get-dotenv/cliHost';
+import type { Command } from 'commander';
+
+import { helloPlugin } from './plugins/hello';
+
+const program: Command = new GetDotenvCli('__CLI_NAME__').use(helloPlugin());
+
+await (program as unknown as GetDotenvCli).resolveAndLoad();
+await program.parseAsync();

package/templates/cli/ts/plugins/hello.ts

@@ -0,0 +1,17 @@
+import { definePlugin } from '@karmaniverous/get-dotenv/cliHost';
+
+export const helloPlugin = () =>
+  definePlugin({
+    id: 'hello',
+    setup(cli) {
+      cli
+        .ns('hello')
+        .description('Say hello with current dotenv context')
+        .action(async () => {
+          const ctx = cli.getCtx?.();
+          const name = '__CLI_NAME__';
+
+          console.log(`[${name}] dotenv keys:`, Object.keys(ctx?.dotenv ?? {}));
+        });
+    },
+  });