Getting Started
Get up and running with xenvsync in under a minute.
Prerequisites
- Node.js 16+ (for npm install) or Go 1.22+ (for go install)
- Or download a prebuilt binary
1. Install
Install via npmbash
$ npm install -g xenvsync
Or via Gobash
$ go install github.com/nasimstg/xenvsync@latest
See Installation for all methods.
2. Initialize Your Project
Run this in your project root. It generates a 256-bit encryption key and adds it to .gitignore.
Initializebash
$ xenvsync init
Generated encryption key → .xenvsync.key (mode 0600)
Updated .gitignore (added .xenvsync.key, .env)
Important: The
.xenvsync.key file is your decryption key. Never commit it. Share it with teammates through a secure channel.3. Create Your .env File
.envenv
DB_HOST=localhost
DB_PORT=5432
API_KEY=sk-your-secret-key
JWT_SECRET=super-secret-jwt-token
4. Encrypt (Push)
Encrypt your .env into .env.vault— this file is safe to commit.
Encryptbash
$ xenvsync push
Encrypted 4 variable(s) → .env.vault
$ git add .env.vault
$ git commit -m "add encrypted env"
5. Decrypt (Pull)
On another machine, after cloning and copying the key:
Decryptbash
$ xenvsync pull
Decrypted 4 variable(s) → .env
6. Run with Injected Secrets
Instead of writing a .env file, inject secrets directly into a process. Plaintext only exists in the child process memory.
In-memory injectionbash
$ xenvsync run -- npm start
$ xenvsync run -- python app.py
$ xenvsync run -- docker compose up
Typical Workflow
Developer A Git Repository Developer B ─────────── ────────────── ─────────── .env (plaintext) │ ├── xenvsync push ──► .env.vault (encrypted) │ │ │ git push │ │ │ git pull ◄─────────────┐ │ │ │ │ .env.vault ──► xenvsync pull │ │ │ .env (plaintext) │ │ └── xenvsync run xenvsync run