@cldmv/envm

@cldmv/envm is a modern, cross-platform environment variable manager for Node.js projects. Designed for both developers and automation, it lets you safely read, write, and manipulate environment variables on Windows and POSIX systems—without ever touching a class. With robust backup and restore features, a powerful CLI, and a clean, ESM-first API, envm makes managing your environment variables simple, safe, and scriptable. Whether you're tweaking your PATH, rolling back a bad change, or automating setup across platforms, envm gives you the control and confidence you need.

Features

• Cross-platform: Works on Windows (registry) and POSIX (dotfiles, /etc/environment)
• No classes: API is plain objects and functions
• Full ESM: Modern, standards-based module
• PATH-like helpers: Manipulate PATH and similar variables safely
• Backup/restore: Automatic, timestamped backups with purge and rollback
• CLI: Powerful envm command for scripting and automation
• TypeScript-friendly: JSDoc-annotated API
• Lightweight: Only ~29 KB minified (core + CLI)

Installation

npm install @cldmv/envm

Usage

Node.js API

import{envManager}from"@cldmv/envm";// Get a variable (expanded)constvalue=awaitenvManager.getExpanded("PATH",{scope: "user"});// Set a variableawaitenvManager.set("MY_VAR","value",{scope: "user"});// Unset a variableawaitenvManager.unset("MY_VAR",{scope: "user"});// PATH helpersawaitenvManager.path.prepend({name: "PATH",scope: "user",values: ["/usr/local/bin"]});awaitenvManager.path.append({name: "PATH",scope: "user",values: ["/opt/bin"]});awaitenvManager.path.remove({name: "PATH",scope: "user",values: ["/opt/bin"]});awaitenvManager.path.sort({name: "PATH",scope: "user"});awaitenvManager.path.unique({name: "PATH",scope: "user"});// Backup helpersawaitenvManager.backup.list({scope: "user"});awaitenvManager.backup.restore("user-PATH-2025-08-11T12-00-00-000Z.bak");awaitenvManager.backup.purge({maxPerScope: 10,maxAgeDays: 7});

CLI

npx envm get --name PATH --scope user
npx envm set --name MY_VAR --value hello --scope user
npx envm unset --name MY_VAR --scope user
npx envm path prepend --name PATH --values /usr/local/bin --scope user
npx envm backup list --scope user
npx envm backup restore user-PATH-2025-08-11T12-00-00-000Z.bak
npx envm --version

CLI Options

• --name/-n — Variable name
• --value/-v — Value to set
• --scope — session, user, or system
• --raw — Get raw value (no expansion)
• --expanded — Get expanded value
• --backup — Enable/disable backup (default: true)
• --verify — Enable/disable verification (default: true)
• --dry-run — Simulate changes

PATH Subcommands

• prepend, append, remove, sort, unique, get

Backup Subcommands

• list, restore

API Reference

See JSDoc in source for full details. Key methods:

• envManager.getRaw(name, { scope })
• envManager.getExpanded(name, { scope })
• envManager.set(name, value, { scope, backup, verify, rollbackOnFail })
• envManager.unset(name, { scope, backup, verify, rollbackOnFail })
• envManager.path.{get,prepend,append,remove,sort,unique}({ ... })
• envManager.backup.{list,restore,setBackupDir,getBackupDir,purge}({ ... })

Scopes

• session: Only affects current process
• user: User profile (Windows registry or ~/.profile)
• system: System-wide (Windows registry or /etc/environment)

Safety

• All changes to user/system env are backed up (unless --backup false)
• Rollback is attempted on failure if backup is enabled
• Backups are timestamped and auto-purged

License

Apache-2.0 © Shinrai / CLDMV