Skip to main content
This guide will help you install env-twin and perform your first environment file synchronization.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 16.0.0 or higher installed
  • A project with at least one .env file
  • npm, yarn, pnpm, or bun package manager
env-twin works with any Node.js project that uses .env files for environment configuration.

​
Installation and first sync

1

Install env-twin

Add env-twin to your project as a development dependency:
npm install --save-dev env-twin
You can also use npx env-twin without installing to try it out first.
2

Run your first sync

Navigate to your project directory and run the sync command:
npx env-twin sync
env-twin will automatically:
  • Detect all .env* files in your current directory
  • Analyze differences between files
  • Prompt you to resolve missing keys
  • Create a backup before making changes
Found 4 .env* file(s):
  - .env
  - .env.local
  - .env.development
  - .env.example

Source of Truth: Union of all files

Missing keys detected:
  - API_KEY (in .env, missing from .env.local, .env.development)
  - DB_HOST (in .env.local, missing from .env, .env.example)

How would you like to handle missing keys?
> Add empty values
  Copy from source
  Skip

✓ Created backup: .env-twin/20241125-143022
✓ Synced 12 environment variables
✓ All files up to date
3

Verify the results

Check your environment files to see the synchronized keys:
# View the changes
cat .env.example

# Check the backup was created
ls -la .env-twin/
env-twin preserves all comments, formatting, and existing values. It only adds missing keys.
4

Commit your changes

After verifying the sync results, commit your changes:
git add .env.example
git commit -m "Sync environment variable keys with env-twin"
Never commit your .env files containing sensitive values! Only commit .env.example files with placeholder values.
Add the backup directory to your .gitignore:
.gitignore
# env-twin backups
.env-twin/

​
What happened?

When you ran npx env-twin sync, the tool:
  1. Discovered files - Scanned your directory for all .env* files
  2. Created a backup - Saved a timestamped backup to .env-twin/ directory
  3. Analyzed differences - Compared environment variable keys across all files
  4. Synchronized keys - Added missing keys to ensure all files have matching variables
  5. Preserved values - Kept existing values intact, only adding new keys

​
Next steps

Explore commands

Learn about all available env-twin commands

Backup management

Understand how to manage and restore backups

Best practices

Follow recommended workflows for your team

CI/CD integration

Automate env-twin in your deployment pipeline

​
Common operations

​
Create .env.example from .env

If you only need to generate a .env.example file from your .env: 
npx env-twin
This default command copies keys from .env to .env.example with sanitized placeholder values.

​
Restore from backup

If you need to undo changes: 
npx env-twin restore
This automatically restores the most recent backup.

​
Clean old backups

To save disk space, clean up old backups: 
npx env-twin clean-backups --keep 5
This keeps the 5 most recent backups and deletes the rest.

​
Troubleshooting

If you see a “command not found” error, make sure you’ve installed env-twin:
npm install --save-dev env-twin
Then use npx to run it:
npx env-twin sync
env-twin looks for environment files in your current directory. Make sure you’re in the right project folder:
cd /path/to/your/project
npx env-twin sync
If you encounter permission errors, check that you have write access to the directory:
# Check permissions
ls -la .env

# Fix permissions if needed
chmod 644 .env*
See the troubleshooting guide for more help.

​
Get help

Need more assistance?
Use npx env-twin --help to see all available options and commands.

Build docs developers (and LLMs) love

Get started for freeTalk to us