Pass multiple .env files on the CLI #1248

Activity

1. OrbisK commented on Mar 13, 2026

   

   OrbisK

   on Mar 13, 2026

   Member

   More actions

   This might be an upstream issue at https://github.com/unjs/citty
2. OrbisK

   added

   upstream

   on Mar 13, 2026
3. OrbisK

   transferred this issue fromnuxt/nuxton Mar 13, 2026
4. antonyharfield commented on May 18, 2026

   

   antonyharfield

   on May 18, 2026

   Last edited by antonyharfield

   More actions

   It is an upstream issue... citty v0.2.0 replaced its custom parser with Node.js's native util.parseArgs.

   ---

   Workaround

   Use dotenv-cli and pass in your list of env files:

   dotenv -e .env.development -e .env -- nuxt dev
   

   ---

   Root Cause Analysis

   The bug has three layers, each responsible to a different package.

   Layer 1 — node:util.parseArgs: the multiple flag

   Node.js's built-in util.parseArgs (introduced in v18.3, stable in v20) has a multiple option per argument. When it's false (the default), repeated flags use last-wins semantics:

   --dotenv .env --dotenv .env.development  →  { dotenv: '.env.development' }
   

   When multiple: true, all values are collected into an array:

   --dotenv .env --dotenv .env.development  →  { dotenv: ['.env', '.env.development'] }
   

   Layer 2 — citty 0.2.x: never sets multiple: true

   In citty v0.2.0, the custom arg parser was replaced with node:util.parseArgs. The problem is that in _parser.ts, when citty builds the options object passed to util.parseArgs, it never sets multiple: true for any arg type. You can see exactly this in the source:

   // From citty's parseRawArgs() in dist/index.mjs
   for (const name of allOptions) {
     if (!options[name]) options[name] = {
       type: getType(name),    // 'boolean' or 'string'
       default: defaults[name]
       // ← no `multiple: true` ever
     };
   }

   Before v0.2.0, citty had its own hand-rolled parser that accumulated repeated flags into arrays. The switch to util.parseArgs silently dropped that behavior.

   Layer 3 — nuxi (@nuxt/cli): dotenv defined as plain type: "string"

   In nuxi's shared args definition:

   // node_modules/nuxi/dist/_shared-*.mjs
   const dotEnvArgs = {
     dotenv: {
       type: "string",
       description: "Path to `.env` file to load, relative to the root directory"
     }
   };

   dotenv is a plain string arg with no indication that it should be repeatable. Even if citty did support a multiple field, nuxi doesn't set it.
5. danielroe

   added the

   Bug

   issue type on Jul 25, 2026
6. danielroe commented on Jul 27, 2026

   

   danielroe

   on Jul 27, 2026

   Member

   More actions

   this will need unjs/citty#258 to be implemented first. possibly via unjs/citty#259.
7. danielroe

   closed this as completedin #1457on Aug 20, 2026