Getting Started

Get up and running with xenvsync in under a minute.

Prerequisites

Homebrew, npm, Go 1.25+, or a prebuilt binary

1. Install

Homebrew (macOS / Linux)bash

$ brew install nasimstg/tap/xenvsync

npmbash

$ npm install -g @nasimstg/xenvsync

Gobash

$ go install github.com/nasimstg/xenvsync@latest

Also available via Scoop, Nix, AUR, and binary downloads.

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. For team sharing, use V2 team mode so each member uses their own X25519 keypair instead.

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

7. Multiple Environments

Use --env to manage staging, production, and other environments separately.

Multi-environmentbash

$ xenvsync push --env staging
Encrypted 3 variable(s) → .env.staging.vault

$ xenvsync pull --env production
Decrypted 5 variable(s) → .env.production

$ xenvsync run --env staging -- npm start

# List all environments
$ xenvsync envs

Merge precedence: .env.shared < .env.staging < .env.local. Use --no-fallback to disable merging.

8. Team Sharing (V2 Vault)

Instead of sharing a symmetric key, each team member generates their own X25519 keypair. The vault is encrypted individually for each member.

Set up team sharingbash

# Each member generates their identity (once)
$ xenvsync keygen
Your public key: dGhpcyBpcyBhIGJhc2U2NCBwdWJsaWMga2V5...

# Project lead adds members to the roster
$ xenvsync team add alice <alice-public-key>
$ xenvsync team add bob <bob-public-key>

# Push auto-detects roster → creates V2 vault
$ xenvsync push
Encrypted 4 variable(s) → .env.vault (V2, 3 recipient(s))

# Each member decrypts with their own private key
$ xenvsync pull

Note: To revoke a member and rotate keys in one step: xenvsync rotate --revoke <name>

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

Next Steps

Command Reference

All 18 commands, flags, and aliases

Security Model

AES-256-GCM, X25519, passphrase protection

Migration Guides

From dotenv-vault, sops, or git-crypt

Installation

Homebrew, Scoop, npm, Nix, AUR, binary

Next Installation