Dotenv (.env)
Create .env and .env.sample files pre-populated with Nova-related environment variables.
Why Use This Command?
- Generates
.envand.env.samplefor every workspace that declaresenvironment.workspacesvalues, so each workspace in a monorepo gets its own files (including the repo root./when it is declared). - Pre-populates Nova CLI logger settings and Node.js defaults so contributors know which variables are available.
- Keeps sensitive values out of version control while documenting the expected shape.
- Reads each workspace's environment values from
nova.config.jsonso the same keys and defaults apply on every run. - Preserves the values already filled into an existing
.env, so regenerating never overwrites a real secret.
Requirements
- Node.js runtime — Use any Node.js LTS release.
- Project root — Run the command from the directory containing the top-level
package.json.
Usage
Options
| Flag | Description |
|---|---|
-d, --dry-run | Run without writing any files. |
-r, --replace-file | Overwrite the existing file instead of creating a .nova-backup copy. |
--prune | Ask before removing .env keys that are no longer declared. |
Config Fields
Declare workspace environment values under environment.workspaces.<path>.variables in nova.config.json, keyed by the workspace path. Any workspace without an environment.workspaces entry is skipped — the repo root included.
The repo root gets .env/.env.sample only when you declare environment.workspaces["./"] (for example, prefix "ROOT_" with no variables).
| Field | Description |
|---|---|
environment.workspaces.<path>.variables | The variables appended to that workspace's generated .env files. See Value Fields. |
This command writes every workspace value regardless of its reach. It reads key and defaultValue for the files; the publish workflow uses reach and secret for GitHub provisioning and CI delivery.
A permitted defaultValue seeds .env.sample; the .env entry is always left blank so real values stay out of version control. Managed values accept no default, so they appear blank in both files for local input.
The NODE_ENV, LOG_LEVEL, and LOG_TIME keys are reserved. The template manages them, so declaring any of them under environment.workspaces.<path>.variables is rejected when the config loads, with a warning naming the reserved key.
These three remain the only unprefixed, template-managed keys.
Output Files
The command writes these files into each workspace directory that declares an environment.workspaces entry, including the repo root ./ only when it is declared.
| File | Description |
|---|---|
.env | Local environment values, preserving any already filled in. |
.env.sample | Shareable template documenting each key with its config default. |
How It Works
The command reads nova.config.json, then generates .env and .env.sample for every workspace that declares an environment.workspaces entry. Normal runs are non-interactive; --prune asks before deleting undeclared keys from an existing .env.
To change a workspace's variables, edit its environment.workspaces entry directly in nova.config.json.
This command writes the double-quoted values; the Dotenv Suite verifies them, so a hand-edited file that drifts from the convention is caught during testing.
Template Output
Each generated file starts from a built-in template that ships three reserved keys with sensible defaults and an inline comment listing their valid values: NODE_ENV (development | production | test, default development), LOG_LEVEL (debug | info | warn | error | auto, default auto, where auto derives the level from NODE_ENV), and LOG_TIME (true | false, default false). Each variable under environment.workspaces.<path>.variables is appended as KEY="" to .env and KEY="<defaultValue>" to .env.sample.
When a workspace declares no variables, the generator emits the template only.
Value Preservation
For .env, the generator reads any existing file in the workspace first and keeps the values already filled in for every declared key — including the reserved NODE_ENV, LOG_LEVEL, and LOG_TIME keys. Only newly-added keys are written blank as KEY="", so regenerating after editing the config never overwrites a real secret.
The .env.sample file is always rebuilt from the config defaults, since it holds no secrets.
Pruning Undeclared Keys
By default, an existing .env line survives even after its key is removed from nova.config.json. This prevents a filled local value from disappearing silently.
Pass --prune to list the undeclared keys for each affected file and ask whether to remove them. Declining or canceling preserves every line, and --dry-run --prune never prompts or removes anything.