Cross-platform dotfile and secret manager with Git-based encrypted storage
npm install envmaticbash
npm install -g envmatic
`
Or use with npx:
`bash
npx envmatic init
`
Quick Start
$3
`bash
envmatic init
`
You'll be prompted for:
- Your private Git repository URL
- Encryption preference (password or SSH key)
- File protection settings
$3
`bash
envmatic add
`
Or import an existing file:
`bash
envmatic import .env --project myapp --environment development
`
$3
`bash
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
$3
#### envmatic init
Initialize Envmatic with a Git repository.
`bash
envmatic init [options]
`
| Option | Description |
|--------|-------------|
| -f, --force | Force re-initialization (overwrites current settings) |
#### envmatic status
Show current status and configuration.
`bash
envmatic status [options]
`
| Option | Description |
|--------|-------------|
| --json | Output as JSON |
---
$3
#### envmatic change-password
Change your encryption password. Requires the current password to decrypt and re-encrypt all files.
`bash
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).
`bash
envmatic rotate-key
`
Allows you to:
- Switch from password to SSH key encryption
- Switch from SSH key to password encryption
- Disable encryption (not recommended)
---
$3
#### envmatic add
Add a new env file to the vault interactively.
`bash
envmatic add [options]
`
| Option | Description |
|--------|-------------|
| -p, --project | Project name |
| -e, --environment | Environment name |
| -n, --name | File name (default: .env) |
| -d, --description | Description |
#### envmatic import
Import an existing .env file into the vault.
`bash
envmatic import [options]
`
| Option | Description |
|--------|-------------|
| -p, --project | Project name |
| -e, --environment | Environment name |
| -n, --name | File name |
| -d, --description | Description |
Example:
`bash
envmatic import .env --project myapp --environment development
`
#### envmatic list
List all env files in the vault.
`bash
envmatic list [options]
Alias: envmatic ls
`
| Option | Description |
|--------|-------------|
| -p, --project | Filter by project |
| --json | Output as JSON |
#### envmatic show
Display contents of an env file.
`bash
envmatic show [file-id] [options]
Alias: envmatic get
`
| Option | Description |
|--------|-------------|
| -r, --reveal | Reveal full values (not masked) |
| --json | Output as JSON |
Example:
`bash
envmatic show myapp/development/.env --reveal
`
#### envmatic edit
Edit an env file interactively or with an external editor.
`bash
envmatic edit [file-id] [options]
`
| Option | Description |
|--------|-------------|
| -e, --editor | Open in external editor (Vim, Neovim, VS Code, etc.) |
Interactive mode (default):
`bash
envmatic edit myapp/development/.env
`
External editor mode:
`bash
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.
`bash
envmatic set
`
Example:
`bash
envmatic set myapp/production/.env API_KEY sk-1234567890
`
#### envmatic unset
Remove a variable from an env file.
`bash
envmatic unset
`
Example:
`bash
envmatic unset myapp/production/.env OLD_API_KEY
`
#### envmatic delete
Delete an env file from the vault.
`bash
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.
`bash
envmatic lock [file-id] [options]
`
| Option | Description |
|--------|-------------|
| -a, --all | Lock all unlocked files |
Examples:
`bash
List and lock unlocked files interactively
envmatic lock
Lock a specific file
envmatic lock myapp/development/.env
Lock all unlocked files
envmatic lock --all
`
---
$3
#### envmatic use
Import an env file into the current project.
`bash
envmatic use [file-id] [options]
`
| Option | Description |
|--------|-------------|
| -o, --output | Output file path (default: .env) |
| -s, --symlink | Create symlink instead of copy |
| -f, --force | Overwrite without confirmation |
Example:
`bash
envmatic use myapp/production/.env --output .env.production
`
#### envmatic pull
Auto-detect project and pull matching env file.
`bash
envmatic pull [options]
`
| Option | Description |
|--------|-------------|
| -e, --env | Environment name (development, production, etc.) |
| -o, --output | Output file path (default: .env) |
| -s, --symlink | Create symlink instead of copy |
| -f, --force | Overwrite without confirmation |
Example:
`bash
cd myapp
envmatic pull --env production --output .env
`
#### envmatic link
Create a symlink to an env file.
`bash
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:
`bash
envmatic link myapp/development/.env ./.env
`
#### envmatic copy
Create a decrypted copy of an env file.
`bash
envmatic copy [file-id] [target] [options]
`
| Option | Description |
|--------|-------------|
| -a, --auto-sync | Auto-sync on changes |
Example:
`bash
envmatic copy myapp/production/.env ./.env
`
#### envmatic unlink
Remove a linked file.
`bash
envmatic unlink [target]
`
#### envmatic links
List all linked files.
`bash
envmatic links [options]
`
| Option | Description |
|--------|-------------|
| --json | Output as JSON |
---
$3
#### envmatic sync
Sync vault with remote repository.
`bash
envmatic sync [options]
`
| Option | Description |
|--------|-------------|
| --push | Push only |
| --pull | Pull only |
#### envmatic sync-links
Update all copied files from vault.
`bash
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).
$3
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
`
$3
Uses your existing SSH private key for encryption. No password prompt needed if your key is loaded in ssh-agent.
$3
`bash
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:
`typescript
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
1. Private Repository: Always use a private Git repository
2. Access Control: Use Git's access controls to limit who can access secrets
3. Encryption: Enable encryption for sensitive production secrets
4. SSH Keys: Consider using SSH key encryption for convenience with security
5. File Permissions: Enable immutable mode to prevent accidental changes
6. Password Storage: Use a password manager; there's no recovery mechanism
---
Configuration
Configuration is stored in ~/.envmatic/config.json:
`json
{
"repoUrl": "git@github.com:you/secrets.git",
"encryptionEnabled": true,
"encryptionMethod": "password",
"immutableByDefault": true,
"branch": "main"
}
`
---
Troubleshooting
$3
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.
$3
Envmatic uses your system's Git configuration. Make sure you can:
`bash
git clone
`
$3
If you're having trouble with encryption:
1. Verify your password is correct
2. For SSH, ensure your key is readable: ssh-keygen -y -f ~/.ssh/id_rsa
3. The encryption salt is stored in your vault - don't delete .envmatic-salt
$3
If you edited files with --editor and forgot to lock them:
`bash
envmatic lock
``