Command Reference

Complete reference for all xenvsync commands, flags, and usage examples.

Quick Reference

Command	Alias	Description
init	—	Generates a cryptographically secure 256-bit AES key, saves it to
push	encrypt	Reads the plaintext
pull	decrypt	Reads the encrypted
run	—	Decrypts the vault in-memory and spawns a child process with the decrypted variables merged into the environment
diff	—	Decrypts the vault and compares its contents to the current
status	—	Reports the presence and last-modified time of
version	—	Prints the version, commit hash, and build date

init

Generates a cryptographically secure 256-bit AES key, saves it to .xenvsync.key with owner-only permissions (0600), and ensures the key file and .env are in .gitignore.

Usage

xenvsync init [flags]

Flags

--force, -f

Overwrite existing key file (regenerate key)

Example

$ xenvsync init
Generated encryption key → .xenvsync.key (mode 0600)
Updated .gitignore (added .xenvsync.key, .env)

# Regenerate key
$ xenvsync init --force

push

alias: encrypt

Reads the plaintext .env file, encrypts it using AES-256-GCM, and writes the ciphertext to .env.vault. The vault file is safe to commit to version control.

Usage

xenvsync push [flags]

Flags

--env, -e	Path to the .env file (default: .env)
--out, -o	Path to the output vault file (default: .env.vault)

Example

$ xenvsync push
Encrypted 5 variable(s) → .env.vault

# Custom paths
$ xenvsync push -e .env.production -o .env.production.vault

pull

alias: decrypt

Reads the encrypted .env.vault, decrypts it using the local .xenvsync.key, and writes the plaintext variables to .env.

Usage

xenvsync pull [flags]

Flags

--vault, -v	Path to the vault file (default: .env.vault)
--out, -o	Path to the output .env file (default: .env)

Example

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

# Custom paths
$ xenvsync pull -v .env.staging.vault -o .env.staging

run

Decrypts the vault in-memory and spawns a child process with the decrypted variables merged into the environment. Plaintext secrets never touch disk — they exist only in the child process's memory.

Usage

xenvsync run [flags] -- <command> [args...]

Flags

--vault, -v

Path to the vault file (default: .env.vault)

Example

$ xenvsync run -- npm start
$ xenvsync run -- python manage.py runserver
$ xenvsync run -- docker compose up
$ xenvsync run -v .env.staging.vault -- node server.js

diff

Decrypts the vault and compares its contents to the current .env file. Shows added, removed, and changed variables.

Usage

xenvsync diff [flags]

Flags

--env, -e	Path to the .env file (default: .env)
--vault, -v	Path to the vault file (default: .env.vault)

Example

$ xenvsync diff
+ NEW_KEY=value     (in .env only, not yet pushed)
- OLD_KEY=removed   (in vault only, not yet pulled)
~ API_KEY  (changed)
    .env:   sk-new-key
    vault:  sk-old-key

status

Reports the presence and last-modified time of .xenvsync.key, .env, and .env.vault. Warns about insecure key file permissions and suggests whether to push or pull.

Usage

xenvsync status

Example

$ xenvsync status
xenvsync status
───────────────────────────────────────
  Key file  .xenvsync.key     2026-03-21 10:00:00  (0600)
  Env file  .env              2026-03-21 10:05:00  (0644)
  Vault     .env.vault        2026-03-21 09:30:00  (0644)
───────────────────────────────────────
  .env is newer than vault → consider running: xenvsync push

version

Prints the version, commit hash, and build date. Build info is injected at compile time via ldflags.

Usage

xenvsync version

Example

$ xenvsync version
xenvsync v0.1.0
  commit: abc1234
  built:  2026-03-21T00:00:00Z

Global Help

Every command supports --help for inline documentation.

$ xenvsync --help
$ xenvsync push --help

PreviousInstallation Next Security Model