@rse/nunjucks-cli 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 ChangeLog
 =========
 
+2.1.0 (2025-12-26)
+------------------
+
+- REFACTOR: change option -e/--extension to option -p/--plugin
+- IMPROVEMENT: add new option -e for loading custom .env files
+- IMPROVEMENT: add new option -E for loading standard .env files
+
 2.0.0 (2025-12-21)
 ------------------
 

package/Dockerfile

@@ -5,8 +5,8 @@
 #   build arguments (early)
 ARG         IMAGE_PREFIX=docker.io/engelschall/
 ARG         IMAGE_NAME=nunjucks-cli
-ARG         IMAGE_VERSION=2.0.0
-ARG         IMAGE_RELEASE=20251221
+ARG         IMAGE_VERSION=2.1.0
+ARG         IMAGE_RELEASE=20251226
 ARG         IMAGE_ALIAS=latest
 
 #   derive image from a certain base image

package/README.md

@@ -61,7 +61,7 @@ $ nunjucks
   [-C|--option <key>=<value>]
   [-d|--defines <context-file>]
   [-D|--define <key>=<value>]
-  [-e|--extension <module-name>]
+  [-p|--plugin <module-name>]
   [-o|--output <output-file>|-]
   <input-file>|-
 ```
@@ -80,8 +80,8 @@ $ nunjucks
 - `-D`|`--define` `<key>=<value>`:<br/>
   Set context definition key/value.
   Can occur multiple times.
-- `-e`|`--extension` `<module-name>`:<br/>
-  Load Nunjucks JavaScript extension module (installed via NPM).
+- `-p`|`--plugin` `<module-name>`:<br/>
+  Load Nunjucks JavaScript plugin module (installed via NPM).
 - `-o`|`--output` `<output-file>`|`-`:<br/>
   Save output file (or stdout).
 - `<input-file>`|`-`:<br/>

package/nunjucks.1

@@ -1,9 +1,9 @@
-.TH "NUNJUCKS" "1" "June 2025" "" ""
+.TH "NUNJUCKS" "1" "December 2025" "" ""
 .SH "NAME"
 \fBnunjucks\fR - Template Rendering Engine
 .SH "SYNOPSIS"
 .P
-\fBnunjucks\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-V\fR|\fB--version\fR\[rB] \[lB]\fB-c\fR|\fB--config\fR \fIconfig-file\fR\[rB] \[lB]\fB-C\fR|\fB--option\fR \fIkey\fR=\fIvalue\fR\[rB] \[lB]\fB-d\fR|\fB--defines\fR \fIcontext-file\fR\[rB] \[lB]\fB-D\fR|\fB--define\fR \fIkey\fR=\fIvalue\fR\[rB] \[lB]\fB-e\fR|\fB--extension\fR \fImodule-name\fR\[rB] \[lB]\fB-o\fR|\fB--output\fR \fIoutput-file\fR|\fB-\fR\[rB] \[lB]\fIinput-file\fR|\fB-\fR\[rB]
+\fBnunjucks\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-V\fR|\fB--version\fR\[rB] \[lB]\fB-e\fR|\fB--env\fR \fIenv-file\fR\[rB] \[lB]\fB-E\fR|\fB--envs\fR\[rB] \[lB]\fB-c\fR|\fB--config\fR \fIconfig-file\fR\[rB] \[lB]\fB-C\fR|\fB--option\fR \fIkey\fR=\fIvalue\fR\[rB] \[lB]\fB-d\fR|\fB--defines\fR \fIcontext-file\fR\[rB] \[lB]\fB-D\fR|\fB--define\fR \fIkey\fR=\fIvalue\fR\[rB] \[lB]\fB-p\fR|\fB--plugin\fR \fImodule-name\fR\[rB] \[lB]\fB-o\fR|\fB--output\fR \fIoutput-file\fR|\fB-\fR\[rB] \[lB]\fIinput-file\fR|\fB-\fR\[rB]
 .SH "DESCRIPTION"
 .P
 \fBnunjucks\fR(1) is a small command-line utility to render templates with the rich and powerful templating language \fBMozilla Nunjucks\fR \fI\(lahttps://mozilla.github.io/nunjucks/\(ra\fR. This allows you to define your configuration in a YAML file and then render an output file based on a template input file where your configuration can be expanded. It optionally can load Nunjucks addons like the ones from the companion \fBNunjucks Addons\fR \fI\(lahttps://github.com/rse/nunjucks-addons\(ra\fR package.
@@ -12,23 +12,27 @@
 The following top-level options and arguments exist:
 .RS 0
 .IP \(bu 4
-\[lB]\fB-h\fR|\fB--help\fR\[rB] Show usage help.
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage help.
 .IP \(bu 4
-\[lB]\fB-V\fR|\fB--version\fR\[rB] Show program version information.
+\[lB]\fB-V\fR|\fB--version\fR\[rB]: Show program version information.
 .IP \(bu 4
-\[lB]\fB-c\fR|\fB--config\fR \fIconfig-file\fR\[rB] Load Nunjucks configuration YAML file.
+\[lB]\fB-e\fR|\fB--env\fR \fIenv-file\fR\[rB]: Load environment file with key/value definitions. These can later be accessed with the global \fBenv\fR variable.
 .IP \(bu 4
-\[lB]\fB-C\fR|\fB--option\fR \fIkey\fR=\fIvalue\fR\[rB] Set Nunjucks configuration option.
+\[lB]\fB-E\fR|\fB--envs\fR\[rB]: Automatically load environment files with key/value definitions from all \fB.env\fR files in current and all parent directories.
 .IP \(bu 4
-\[lB]\fB-d\fR|\fB--defines\fR \fIcontext-file\fR\[rB] Load context definition YAML file. Can occur multiple times.
+\[lB]\fB-c\fR|\fB--config\fR \fIconfig-file\fR\[rB]: Load Nunjucks configuration YAML file.
 .IP \(bu 4
-\[lB]\fB-D\fR|\fB--define\fR \fIkey\fR=\fIvalue\fR\[rB] Set context definition key/value. Can occur multiple times.
+\[lB]\fB-C\fR|\fB--option\fR \fIkey\fR=\fIvalue\fR\[rB]: Set Nunjucks configuration option.
 .IP \(bu 4
-\[lB]\fB-e\fR|\fB--extension\fR \fImodule-name\fR\[rB] Load Nunjucks JavaScript extension module (installed via NPM).
+\[lB]\fB-d\fR|\fB--defines\fR \fIcontext-file\fR\[rB]: Load context definition YAML file. Can occur multiple times.
 .IP \(bu 4
-\[lB]\fB-o\fR|\fB--output\fR \fIoutput-file\fR|\fB-\fR\[rB] Save output file (or stdout).
+\[lB]\fB-D\fR|\fB--define\fR \fIkey\fR=\fIvalue\fR\[rB]: Set context definition key/value. Can occur multiple times.
 .IP \(bu 4
-\[lB]\fB<input-file>\fR|\fB-\fR\[rB] Load input file (or stdin).
+\[lB]\fB-p\fR|\fB--plugin\fR \fImodule-name\fR\[rB]: Load Nunjucks JavaScript plugin module (installed via NPM).
+.IP \(bu 4
+\[lB]\fB-o\fR|\fB--output\fR \fIoutput-file\fR|\fB-\fR\[rB]: Save output file (or stdout).
+.IP \(bu 4
+\[lB]\fB<input-file>\fR|\fB-\fR\[rB]: Load input file (or stdin).
 .RE 0
 
 .SH "EXAMPLE"

package/nunjucks.js

@@ -14,6 +14,8 @@ import chalk from "chalk";
 import jsYAML from "js-yaml";
 import nunjucks from "nunjucks";
 import deepmerge from "deepmerge";
+import dotenvx from "@dotenvx/dotenvx";
+import * as findup from "find-up";
 /*  load my own information  */
 const my = JSON.parse(await fs.promises.readFile(new URL("./package.json", import.meta.url), "utf-8"));
 /*  parse command-line arguments  */
@@ -24,11 +26,13 @@ program.name("nunjucks")
     .showHelpAfterError("hint: use option --help for usage information")
     .option("-h, --help", "show usage help", false)
     .option("-V, --version", "show program version information", false)
+    .option("-e, --env <env-file>", "load environment key/value file", reduceArray, [])
+    .option("-E, --envs", "load all environment key/value files", false)
     .option("-c, --config <config-file>", "load Nunjucks configuration YAML file", "")
     .option("-C, --option <key>=<value>", "set Nunjucks configuration option", reduceArray, [])
     .option("-d, --defines <context-file>", "load context definition YAML file", reduceArray, [])
     .option("-D, --define <key>=<value>", "set context definition key/value", reduceArray, [])
-    .option("-e, --extension <module-name>", "load Nunjucks JavaScript extension module", reduceArray, [])
+    .option("-p, --plugin <module-name>", "load Nunjucks JavaScript plugin module", reduceArray, [])
     .option("-o, --output <output-file>", "save output file", "-")
     .argument("[<input-file>]", "input file");
 program.parse(process.argv);
@@ -82,7 +86,7 @@ if (inputFile === "-") {
 }
 else {
     if (!fs.existsSync(inputFile)) {
-        console.error(chalk.red(`nunjucks: ERROR: failed to find input file: ${inputFile}`));
+        console.error(chalk.red(`nunjucks: ERROR: failed to find input file: "${inputFile}"`));
         process.exit(1);
     }
     input = fs.readFileSync(inputFile, { encoding: "utf8" });
@@ -98,6 +102,22 @@ for (const define of argv.defines) {
         process.exit(1);
     }
 }
+/*  load environment variables from all default files  */
+if (argv.envs) {
+    const files = findup.findUpMultipleSync(".env");
+    if (files.length > 0)
+        dotenvx.config({ path: files, quiet: true });
+}
+/*  load environment variables from environment files  */
+if (argv.env.length > 0) {
+    for (const env of argv.env) {
+        if (!fs.existsSync(env)) {
+            console.error(chalk.red(`nunjucks: ERROR: environment file not found: "${env}"`));
+            process.exit(1);
+        }
+    }
+    dotenvx.config({ path: argv.env, quiet: true });
+}
 /*  expose environment variables to template  */
 context.env = process.env;
 /*  add context defines  */
@@ -136,20 +156,20 @@ options = {
 };
 /*  configure environment  */
 const env = nunjucks.configure(inputFile, options);
-/*  load external extension files  */
-for (const extension of argv.extension) {
-    let modpath = path.resolve(extension);
+/*  load external plugin modules  */
+for (const plugin of argv.plugin) {
+    let modpath = path.resolve(plugin);
     if (!fs.existsSync(modpath)) {
         try {
             const require = createRequire(import.meta.url);
-            modpath = require.resolve(extension);
+            modpath = require.resolve(plugin);
         }
         catch (_ex) {
             modpath = null;
         }
     }
     if (modpath === null) {
-        console.error(chalk.red(`nunjucks: ERROR: failed to find extension module: ${extension}`));
+        console.error(chalk.red(`nunjucks: ERROR: failed to find plugin module: ${plugin}`));
         process.exit(1);
     }
     /*  dynamically import the module  */
@@ -160,11 +180,11 @@ for (const extension of argv.extension) {
         mod = mod.default ?? mod;
     }
     catch (ex) {
-        console.error(chalk.red(`nunjucks: ERROR: failed to load extension module: ${ex.toString()}`));
+        console.error(chalk.red(`nunjucks: ERROR: failed to load plugin module: ${ex.toString()}`));
         process.exit(1);
     }
     if (!(mod !== null && typeof mod === "function")) {
-        console.error(chalk.red(`nunjucks: ERROR: failed to call extension file: ${modpath}`));
+        console.error(chalk.red(`nunjucks: ERROR: failed to call plugin file: "${modpath}"`));
         process.exit(1);
     }
     mod(env);

package/nunjucks.md

@@ -6,11 +6,13 @@
 `nunjucks`
 \[`-h`|`--help`\]
 \[`-V`|`--version`\]
+\[`-e`|`--env` *env-file*\]
+\[`-E`|`--envs`\]
 \[`-c`|`--config` *config-file*\]
 \[`-C`|`--option` *key*=*value*\]
 \[`-d`|`--defines` *context-file*\]
 \[`-D`|`--define` *key*=*value*\]
-\[`-e`|`--extension` *module-name*\]
+\[`-p`|`--plugin` *module-name*\]
 \[`-o`|`--output` *output-file*|`-`\]
 \[*input-file*|`-`\]
 
@@ -27,33 +29,41 @@ It optionally can load Nunjucks addons like the ones from the companion
 
 The following top-level options and arguments exist:
 
-- \[`-h`|`--help`\]
+- \[`-h`|`--help`\]:
   Show usage help.
 
-- \[`-V`|`--version`\]
+- \[`-V`|`--version`\]:
   Show program version information.
 
-- \[`-c`|`--config` *config-file*\]
+- \[`-e`|`--env` *env-file*\]:
+  Load environment file with key/value definitions.
+  These can later be accessed with the global `env` variable.
+
+- \[`-E`|`--envs`\]:
+  Automatically load environment files with key/value definitions
+  from all `.env` files in current and all parent directories.
+
+- \[`-c`|`--config` *config-file*\]:
   Load Nunjucks configuration YAML file.
 
-- \[`-C`|`--option` *key*=*value*\]
+- \[`-C`|`--option` *key*=*value*\]:
   Set Nunjucks configuration option.
 
-- \[`-d`|`--defines` *context-file*\]
+- \[`-d`|`--defines` *context-file*\]:
   Load context definition YAML file.
   Can occur multiple times.
 
-- \[`-D`|`--define` *key*=*value*\]
+- \[`-D`|`--define` *key*=*value*\]:
   Set context definition key/value.
   Can occur multiple times.
 
-- \[`-e`|`--extension` *module-name*\]
-  Load Nunjucks JavaScript extension module (installed via NPM).
+- \[`-p`|`--plugin` *module-name*\]:
+  Load Nunjucks JavaScript plugin module (installed via NPM).
 
-- \[`-o`|`--output` *output-file*|`-`\]
+- \[`-o`|`--output` *output-file*|`-`\]:
   Save output file (or stdout).
 
-- \[`<input-file>`|`-`\]
+- \[`<input-file>`|`-`\]:
   Load input file (or stdin).
 
 ## EXAMPLE

package/nunjucks.ts

@@ -16,6 +16,8 @@ import chalk             from "chalk"
 import jsYAML            from "js-yaml"
 import nunjucks          from "nunjucks"
 import deepmerge         from "deepmerge"
+import dotenvx           from "@dotenvx/dotenvx"
+import * as findup       from "find-up"
 
 /*  type definitions  */
 type PackageInfo = {
@@ -38,11 +40,13 @@ type OptionsType = {
 type CLIOptions = {
     help:      boolean
     version:   boolean
+    env:       string[]
+    envs:      boolean
     config:    string
     option:    string[]
     defines:   string[]
     define:    string[]
-    extension: string[]
+    plugin:    string[]
     output:    string
     _:         string[]
 }
@@ -58,11 +62,13 @@ program.name("nunjucks")
     .showHelpAfterError("hint: use option --help for usage information")
     .option("-h, --help",                    "show usage help",                                        false)
     .option("-V, --version",                 "show program version information",                       false)
+    .option("-e, --env <env-file>",          "load environment key/value file",           reduceArray, [])
+    .option("-E, --envs",                    "load all environment key/value files",                   false)
     .option("-c, --config <config-file>",    "load Nunjucks configuration YAML file",                  "")
     .option("-C, --option <key>=<value>",    "set Nunjucks configuration option",         reduceArray, [])
     .option("-d, --defines <context-file>",  "load context definition YAML file",         reduceArray, [])
     .option("-D, --define <key>=<value>",    "set context definition key/value",          reduceArray, [])
-    .option("-e, --extension <module-name>", "load Nunjucks JavaScript extension module", reduceArray, [])
+    .option("-p, --plugin <module-name>",    "load Nunjucks JavaScript plugin module",    reduceArray, [])
     .option("-o, --output <output-file>",    "save output file",                                       "-")
     .argument("[<input-file>]", "input file")
 program.parse(process.argv)
@@ -116,7 +122,7 @@ if (inputFile === "-") {
 }
 else {
     if (!fs.existsSync(inputFile)) {
-        console.error(chalk.red(`nunjucks: ERROR: failed to find input file: ${inputFile}`))
+        console.error(chalk.red(`nunjucks: ERROR: failed to find input file: "${inputFile}"`))
         process.exit(1)
     }
     input = fs.readFileSync(inputFile, { encoding: "utf8" })
@@ -134,6 +140,24 @@ for (const define of argv.defines) {
     }
 }
 
+/*  load environment variables from all default files  */
+if (argv.envs) {
+    const files = findup.findUpMultipleSync(".env")
+    if (files.length > 0)
+        dotenvx.config({ path: files, quiet: true })
+}
+
+/*  load environment variables from environment files  */
+if (argv.env.length > 0) {
+    for (const env of argv.env) {
+        if (!fs.existsSync(env)) {
+            console.error(chalk.red(`nunjucks: ERROR: environment file not found: "${env}"`))
+            process.exit(1)
+        }
+    }
+    dotenvx.config({ path: argv.env, quiet: true })
+}
+
 /*  expose environment variables to template  */
 context.env = process.env
 
@@ -176,20 +200,20 @@ options = {
 /*  configure environment  */
 const env = nunjucks.configure(inputFile, options)
 
-/*  load external extension files  */
-for (const extension of argv.extension) {
-    let modpath: string | null = path.resolve(extension)
+/*  load external plugin modules  */
+for (const plugin of argv.plugin) {
+    let modpath: string | null = path.resolve(plugin)
     if (!fs.existsSync(modpath)) {
         try {
             const require = createRequire(import.meta.url)
-            modpath = require.resolve(extension)
+            modpath = require.resolve(plugin)
         }
         catch (_ex) {
             modpath = null
         }
     }
     if (modpath === null) {
-        console.error(chalk.red(`nunjucks: ERROR: failed to find extension module: ${extension}`))
+        console.error(chalk.red(`nunjucks: ERROR: failed to find plugin module: ${plugin}`))
         process.exit(1)
     }
 
@@ -202,11 +226,11 @@ for (const extension of argv.extension) {
         mod = mod.default ?? mod
     }
     catch (ex: any) {
-        console.error(chalk.red(`nunjucks: ERROR: failed to load extension module: ${ex.toString()}`))
+        console.error(chalk.red(`nunjucks: ERROR: failed to load plugin module: ${ex.toString()}`))
         process.exit(1)
     }
     if (!(mod !== null && typeof mod === "function")) {
-        console.error(chalk.red(`nunjucks: ERROR: failed to call extension file: ${modpath}`))
+        console.error(chalk.red(`nunjucks: ERROR: failed to call plugin file: "${modpath}"`))
         process.exit(1)
     }
     mod(env)

package/package.json

@@ -1,8 +1,8 @@
 {
     "name":                       "@rse/nunjucks-cli",
     "publishConfig":              { "access": "public" },
-    "version":                    "2.0.1",
-    "stdver":                     "2.0.0-GA",
+    "version":                    "2.1.0",
+    "stdver":                     "2.1.0-GA",
     "description":                "Nunjucks Template Rendering Command-Line Interface",
     "author": {
         "name":                   "Dr. Ralf S. Engelschall",
@@ -30,7 +30,9 @@
         "chalk":                  "5.6.2",
         "commander":              "14.0.2",
         "js-yaml":                "4.1.1",
-        "deepmerge":              "4.3.1"
+        "deepmerge":              "4.3.1",
+        "@dotenvx/dotenvx":       "1.51.2",
+        "find-up":                "8.0.0"
     },
     "devDependencies": {
         "eslint":                 "9.39.2",
@@ -44,14 +46,15 @@
         "remark":                 "15.0.1",
         "remark-man":             "9.0.0",
         "typescript":             "5.9.3",
-        "typescript-eslint":      "8.50.0",
-        "@rse/stx":               "1.1.3",
+        "typescript-eslint":      "8.50.1",
+        "@rse/stx":               "1.1.4",
         "shx":                    "0.4.0",
         "@yao-pkg/pkg":           "6.11.0",
 
         "@types/node":            "25.0.3",
         "@types/js-yaml":         "4.0.9",
-        "@types/nunjucks":        "3.2.6"
+        "@types/nunjucks":        "3.2.6",
+        "@types/find-up":         "4.0.2"
     },
     "scripts": {
         "start":                  "stx -v4 -c stx.conf",

package/stx.conf

@@ -11,10 +11,7 @@ lint
 
 #   build JavaScript from TypeScript
 build
-    tsc --project tsconfig.json
-
-#   build manual page
-man
+    tsc --project tsconfig.json && \
     remark --quiet --use remark-man --output nunjucks.1 nunjucks.md
 
 #   execute simple smole test