CLI Reference

share-env Documentation

Complete reference for npx share-env push and npx share-env pull — the secure way to share .env files and dotenv files between developers.

Overview

share-env (env-share) eliminates the insecure practice of sharing .env files over Slack, Discord, email, or any messaging platform. It encrypts your environment variables on your local machine before they leave your computer, uploads only the ciphertext to a temporary zero-knowledge relay server, and gives you a one-time share code to pass to your teammate.

The relay server permanently deletes the payload the moment it is pulled. The relay never receives the decryption key — it only ever stores unreadable ciphertext.

Default relay server: https://env-share-1rsi.onrender.com — runs on Render. You can self-host your own relay.

Prerequisites

Node.js 18 or higher
Required by both the CLI and the relay server. Check: node --version
A .gitignore that ignores .env
Required. The tool refuses to run if .gitignore does not contain .env and .env.* rules.
A .env file to share (sender only)
The receiver does not need one — it will be created or merged upon pull.
gitignore — required
# Add to your .gitignore before running share-env
.env
.env.*

Quick Start

No installation required. Run directly with npx.

Sender (Developer A)
bash
$ npx share-env push
Receiver (Developer B)
bash
$ npx share-env pull <share-code>

push

Encrypt and upload the local .env file to the relay server. Returns a one-time share code.

syntax
$ npx share-env push [options]
OptionTypeDefaultDescription
-f, --file <path>string.envPath to the .env file to share
--server <url>stringhttps://env-share-1rsi.onrender.comRelay server base URL
bash — push examples
# Share the default .env in the current directory
$ npx share-env push

# Share a file at a custom path
$ npx share-env push --file ./config/.env.production

# Use a custom self-hosted relay server
$ npx share-env push --server https://your-relay.example.com
Expected output
terminal output
  3 key(s) loaded from .env

  Encrypted payload stored on relay.

  Payload uploaded. Your share code:

  +--------------------------------------------------+
  |  apple-brave-cloud#a3f9b2c1d4e5f6a7b8c9d0e1f2...  |
  +--------------------------------------------------+

  Send the code above to your teammate. It expires in 10 minutes.
  One-time use — it is deleted from the relay after the first pull.

pull

Download, decrypt, and merge a shared .env file from the relay server.

syntax
$ npx share-env pull <share-code> [options]
Arguments
ArgumentRequiredDescription
share-codeYesFull share code from the sender — format: phrase#hexKey
Options
OptionTypeDefaultDescription
-f, --file <path>string.envTarget path to write the decrypted .env
--server <url>stringhttps://env-share-1rsi.onrender.comRelay server base URL
bash — pull examples
# Pull into the default .env in the current directory
$ npx share-env pull apple-brave-cloud#a3f9b2c1...

# Pull into a custom file path
$ npx share-env pull apple-brave-cloud#a3f9b2c1... --file ./config/.env.local

# Pull using a custom relay server
$ npx share-env pull apple-brave-cloud#a3f9b2c1... --server https://your-relay.example.com

Step-by-step workflow

Complete walkthrough for two developers sharing a .env file.

1
Confirm .gitignore is set upDeveloper B

Before anything else, Developer B verifies their local .gitignore contains the required rules. The tool refuses to run on either side if these are missing.

gitignore
.env
.env.*
2
Navigate to the project rootDeveloper A

Developer A opens a terminal and changes to the root of the project where the .env file is located.

bash
$ cd /path/to/your/project
3
Run the push commandDeveloper A

The tool validates .gitignore, reads .env, generates a 256-bit AES key locally, encrypts the file, uploads only ciphertext to the relay, and returns a share code.

bash
$ npx share-env push
4
Send the share code to Developer BDeveloper A

Copy the full share code and send via Slack, Signal, Teams, or any channel. The code is safe to send — the relay only ever saw the identifier portion, not the key after #.

share code
apple-brave-cloud#a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7...
5
Navigate to the project rootDeveloper B
bash
$ cd /path/to/your/project
6
Run the pull commandDeveloper B

The tool validates .gitignore, fetches the encrypted payload, the relay immediately deletes it, decrypts locally, and writes or merges the .env file.

bash
$ npx share-env pull apple-brave-cloud#a3f9b2c1...

Smart merge

If Developer B already has a local .env file, share-env does not overwrite it blindly. It compares each key interactively and asks for resolution on every conflict.

terminal — merge conflict resolution
  Existing .env found — starting merge...

  Conflict: DATABASE_URL
    Local  : postgres://localhost:5432/mydb
    Remote : postgres://prod-host:5432/mydb
  ? Which value do you want to keep?
    > Keep local
      Use remote

  Done!  .env written to: /path/to/your/project/.env

Custom file paths

Use --file (or -f) on both sides to work with staging, production, or any custom-named env file.

bash
# Sender — share a staging env file
$ npx share-env push --file .env.staging

# Receiver — write to the same path
$ npx share-env pull <code> --file .env.staging

Self-hosting the relay

Run your own relay for full infrastructure control. See the self-hosting guide for the complete setup. The short version:

bash — quick setup
$ git clone https://github.com/arjunn881/env-share.git
$ cd env-share
$ npm install
$ npm run build
$ npm start --workspace=server

# Use your relay:
$ npx share-env push --server https://your-relay.example.com
$ npx share-env pull <code> --server https://your-relay.example.com