Sunbelt Computer Software

◆ Envmatic

Your secrets, your control.

Envmatic is a cross-platform CLI tool for managing dotfiles and environment secrets. It uses Git as a secure, private storage backend with optional AES-256 encryption.

Features

🔐 AES-256 Encryption - Protect secrets with password or SSH key
🌐 Git-Based Storage - Use any private Git repository
📁 Organized Structure - Intuitive project/environment hierarchy
🔗 Smart Linking - Symlink or copy secrets to projects
🔒 Immutable Files - Protect against accidental changes
✏️ External Editor Support - Edit with Vim, Neovim, VS Code, etc.
🔄 Password Rotation - Change encryption password or switch methods
🖥️ Cross-Platform - Works on Windows, macOS, and Linux

Installation

npm install -g envmatic

Or use with npx:

npx envmatic init

Quick Start

1. Initialize with your private repo

envmatic init

You'll be prompted for:

Your private Git repository URL
Encryption preference (password or SSH key)
File protection settings

2. Add your first env file

envmatic add

Or import an existing file:

envmatic import .env --project myapp --environment development

3. Use in your project

# Quick: Auto-detect project and pull matching env
cd myapp
envmatic pull

# Or specify environment
envmatic pull --env production

# Or browse and select manually
envmatic use

# Or use a specific file ID
envmatic use "myapp/development/.env"

Commands Reference

Setup & Configuration

`envmatic init`

Initialize Envmatic with a Git repository.

envmatic init [options]

Option	Description
`-f, --force`	Force re-initialization (overwrites current settings)

`envmatic status`

Show current status and configuration.

envmatic status [options]

Option	Description
`--json`	Output as JSON

Security & Encryption

`envmatic change-password`

Change your encryption password. Requires the current password to decrypt and re-encrypt all files.

envmatic change-password

⚠️ Warning: If you forget your password, all encrypted data will be permanently lost.

`envmatic rotate-key`

Rotate encryption key or change encryption method (password ↔ SSH key).

envmatic rotate-key

Allows you to:

Switch from password to SSH key encryption
Switch from SSH key to password encryption
Disable encryption (not recommended)

File Management

`envmatic add`

Add a new env file to the vault interactively.

envmatic add [options]

Option	Description
`-p, --project <name>`	Project name
`-e, --environment <name>`	Environment name
`-n, --name <name>`	File name (default: `.env`)
`-d, --description <text>`	Description

`envmatic import`

Import an existing .env file into the vault.

envmatic import <path> [options]

Option	Description
`-p, --project <name>`	Project name
`-e, --environment <name>`	Environment name
`-n, --name <name>`	File name
`-d, --description <text>`	Description

Example:

envmatic import .env --project myapp --environment development

`envmatic list`

List all env files in the vault.

envmatic list [options]
# Alias: envmatic ls

Option	Description
`-p, --project <name>`	Filter by project
`--json`	Output as JSON

`envmatic show`

Display contents of an env file.

envmatic show [file-id] [options]
# Alias: envmatic get

Option	Description
`-r, --reveal`	Reveal full values (not masked)
`--json`	Output as JSON

Example:

envmatic show myapp/development/.env --reveal

`envmatic edit`

Edit an env file interactively or with an external editor.

envmatic edit [file-id] [options]

Option	Description
`-e, --editor`	Open in external editor (Vim, Neovim, VS Code, etc.)

Interactive mode (default):

envmatic edit myapp/development/.env

External editor mode:

envmatic edit myapp/development/.env --editor

When using --editor, you'll be prompted to choose from available editors on your system.

`envmatic set`

Set a single variable in an env file.

envmatic set <file-id> <key> <value>

Example:

envmatic set myapp/production/.env API_KEY sk-1234567890

`envmatic unset`

Remove a variable from an env file.

envmatic unset <file-id> <key>

Example:

envmatic unset myapp/production/.env OLD_API_KEY

`envmatic delete`

Delete an env file from the vault.

envmatic delete [file-id]
# Alias: envmatic rm

`envmatic lock`

Lock (protect) env files after editing. Lists all unlocked files and allows you to secure them.

envmatic lock [file-id] [options]

Option	Description
`-a, --all`	Lock all unlocked files

Examples:

# List and lock unlocked files interactively
envmatic lock

# Lock a specific file
envmatic lock myapp/development/.env

# Lock all unlocked files
envmatic lock --all

Project Integration

`envmatic use`

Import an env file into the current project.

envmatic use [file-id] [options]

Option	Description
`-o, --output <path>`	Output file path (default: `.env`)
`-s, --symlink`	Create symlink instead of copy
`-f, --force`	Overwrite without confirmation

Example:

envmatic use myapp/production/.env --output .env.production

`envmatic pull`

Auto-detect project and pull matching env file.

envmatic pull [options]

Option	Description
`-e, --env <name>`	Environment name (development, production, etc.)
`-o, --output <path>`	Output file path (default: `.env`)
`-s, --symlink`	Create symlink instead of copy
`-f, --force`	Overwrite without confirmation

Example:

cd myapp
envmatic pull --env production --output .env

`envmatic link`

Create a symlink to an env file.

envmatic link [file-id] [target] [options]

Option	Description
`-c, --copy`	Create a copy instead of symlink
`-a, --auto-sync`	Auto-sync copies on changes

Note: Symlinks only work for unencrypted files. Encrypted files require copy mode.

Example:

envmatic link myapp/development/.env ./.env

`envmatic copy`

Create a decrypted copy of an env file.

envmatic copy [file-id] [target] [options]

Option	Description
`-a, --auto-sync`	Auto-sync on changes

Example:

envmatic copy myapp/production/.env ./.env

`envmatic unlink`

Remove a linked file.

envmatic unlink [target]

`envmatic links`

List all linked files.

envmatic links [options]

Option	Description
`--json`	Output as JSON

Sync

`envmatic sync`

Sync vault with remote repository.

envmatic sync [options]

`envmatic sync-links`

Update all copied files from vault.

envmatic sync-links

Vault Structure

Your secrets are organized in an intuitive hierarchy:

~/.envmatic/vault/
├── myapp/
│   ├── development/
│   │   └── .env.enc
│   ├── staging/
│   │   └── .env.enc
│   └── production/
│       └── .env.enc
├── another-project/
│   └── local/
│       └── .env.enc
└── shared/
    └── common/
        └── .env.enc

Encryption

Envmatic uses AES-256-GCM encryption with PBKDF2 key derivation (100,000 iterations, SHA-512).

Password Mode

You'll be prompted for your password when accessing encrypted files.

⚠️ PASSWORD SECURITY WARNING

Your password is the ONLY way to decrypt your secrets.
There is NO password recovery mechanism.

If you forget your password:
→ All encrypted data will be PERMANENTLY LOST
→ There is NO way to recover your secrets

We strongly recommend:
• Using a password manager to store your password
• Writing it down and storing it securely offline

SSH Key Mode

Uses your existing SSH private key for encryption. No password prompt needed if your key is loaded in ssh-agent.

Changing Password or Encryption Method

# Change password (requires current password)
envmatic change-password

# Switch encryption method (password ↔ SSH key)
envmatic rotate-key

Programmatic Usage

Envmatic can be imported into your Node.js projects:

import {
  readEnvFile,
  listEnvFiles,
  getVariable,
} from 'envmatic';

// List all files
const files = await listEnvFiles();

// Read a file (with encryption options if needed)
const { variables } = await readEnvFile('myapp/development/.env', {
  method: 'password',
  password: process.env.ENVMATIC_PASSWORD,
});

// Get a single variable
const apiKey = await getVariable('myapp/production/.env', 'API_KEY', {
  method: 'ssh',
  sshKeyPath: '~/.ssh/id_rsa',
});

Security Considerations

Private Repository: Always use a private Git repository
Access Control: Use Git's access controls to limit who can access secrets
Encryption: Enable encryption for sensitive production secrets
SSH Keys: Consider using SSH key encryption for convenience with security
File Permissions: Enable immutable mode to prevent accidental changes
Password Storage: Use a password manager; there's no recovery mechanism

Configuration

Configuration is stored in ~/.envmatic/config.json:

{
  "repoUrl": "git@github.com:you/secrets.git",
  "encryptionEnabled": true,
  "encryptionMethod": "password",
  "immutableByDefault": true,
  "branch": "main"
}

Troubleshooting

Symlinks on Windows

Creating symlinks on Windows requires either:

Developer Mode enabled (Settings → Update & Security → For developers)
Running as Administrator

Alternatively, use the --copy flag or envmatic copy command.

Git Authentication

Envmatic uses your system's Git configuration. Make sure you can:

git clone <your-repo-url>

Encryption Issues

If you're having trouble with encryption:

Verify your password is correct
For SSH, ensure your key is readable: ssh-keygen -y -f ~/.ssh/id_rsa
The encryption salt is stored in your vault - don't delete .envmatic-salt

Unlocked Files

If you edited files with --editor and forgot to lock them:

envmatic lock

This will list all unlocked files and let you secure them.

License

MIT

Name		Name	Last commit message	Last commit date
src		src
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Option	Description
`--push`	Push only
`--pull`	Pull only

Sunbelt Computer Software

PL/B Language Development and Support

Latest commit

History

Folders and files

Repository files navigation

◆ Envmatic

Features

Installation

Quick Start

1. Initialize with your private repo

2. Add your first env file

3. Use in your project

Commands Reference

Setup & Configuration

envmatic init

envmatic status

Security & Encryption

envmatic change-password

envmatic rotate-key

File Management

envmatic add

envmatic import

envmatic list

envmatic show

envmatic edit

envmatic set

envmatic unset

envmatic delete

envmatic lock

Project Integration

envmatic use

envmatic pull

envmatic link

envmatic copy

envmatic unlink

envmatic links

Sync

envmatic sync

envmatic sync-links

Vault Structure

Encryption

Password Mode

SSH Key Mode

Changing Password or Encryption Method

Programmatic Usage

Security Considerations

Configuration

Troubleshooting

Symlinks on Windows

Git Authentication

Encryption Issues

Unlocked Files

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`envmatic init`

`envmatic status`

`envmatic change-password`

`envmatic rotate-key`

`envmatic add`

`envmatic import`

`envmatic list`

`envmatic show`

`envmatic edit`

`envmatic set`

`envmatic unset`

`envmatic delete`

`envmatic lock`

`envmatic use`

`envmatic pull`

`envmatic link`

`envmatic copy`

`envmatic unlink`

`envmatic links`

`envmatic sync`

`envmatic sync-links`