EnvLock

EnvLock is a secrets management system for development teams. It consists of a web dashboard, where projects and secrets are organized and controlled, and a command-line tool, which developers use to bring those secrets onto their own machines. It replaces the common practice of sharing .env files over chat or email with a controlled, auditable alternative.

Table of Contents

• How It Works
• Features
• Requirements
• Installation
• Getting Started
• CLI Command Reference
• Security
• Contributing
• Support & Links

How It Works

EnvLock is made up of two parts that work together: a dashboard and a CLI.

The Dashboard

The dashboard, at envlock.app, is where a project actually lives. From there, a project owner can:

• Create a project and invite team members, assigning each person a role (owner, admin, member, or viewer).
• Define environments within that project, typically development, staging, and production, each holding its own independent set of secrets.
• Add, edit, and version secrets under any environment.
• Issue and revoke access tokens, each one scoped to a specific project and to specific environments within it.

Every change made on the dashboard is recorded in an audit log, so a team can see who added or modified a secret, and when.

The CLI

The CLI is what a developer uses day to day, once a project has already been set up on the dashboard. Running envlock login opens a browser window where the developer approves access to a specific project and, depending on the role granted, specific environments within it. That approval only needs to happen once per project folder. After that, secrets can be pulled into a local .env file, or injected directly into a running process, without opening the dashboard again.

In short: the dashboard is where secrets are organized and controlled, and the CLI is how they reach a developer's machine.

Features

• Authentication through a browser-based device authorization flow, rather than pasted API keys.
• Access tokens scoped to a single project and specific environments, so a compromised token cannot expose secrets outside its intended scope.
• Session credentials stored per project folder, so working on multiple EnvLock projects on the same machine does not cause conflicts.
• An option to inject secrets directly into a running process's memory, so plaintext values never need to be written to disk.
• Automatic .gitignore configuration on login, to prevent secrets from being committed by mistake.
• A full audit log on the dashboard, recording who changed which secret and when.

Requirements

• Node.js 18 or later
• An EnvLock account, created at envlock.app

Installation & Usage

EnvLock can be used in either of two ways.

Option A: Zero Install

Run commands directly without a global install. This is the recommended path for CI/CD pipelines, such as GitHub Actions:

npx envlock login
npx envlock pull

Option B: Global Installation

Install once, then run it from anywhere:

npm install -g envlock

envlock login
envlock pull

Getting Started

1. Authenticate

Run the login command inside your project directory:

envlock login

This will print a user code in your terminal, open your browser to complete approval, and prompt you to choose which project this directory should have access to. Once approved, your local .gitignore is updated automatically.

2. Pull Secrets

Write your project's secrets to a local .env file:

envlock pull

Pull from a specific environment:

envlock pull --env production

3. Run Commands with Secrets Injected

Run your application with secrets passed directly into the process, without writing them to disk:

envlock run -- node app.js

Use a different environment:

envlock run --env staging -- npm run dev

CLI Command Reference

Every command supports --help for details on its arguments and options.

Global Flags

| Flag | Description | | --------------- | ---------------------------------------------- | | -h, --help | Show help for the CLI or a specific subcommand | | -V, --version | Output the current version number |

envlock login

Authenticates the current project folder through the device authorization flow: displays a user code, opens the browser, and waits for approval.

envlock login

envlock pull

Downloads decrypted secrets and writes them locally as key-value pairs.

| Option | Description | Default | | --------------------- | --------------------------------------------------- | ------------- | | -e, --env <name> | Environment to pull from | development | | -o, --output <file> | Target filename to write | .env | | --overwrite | Allow overwriting a file that already contains keys | false |

envlock pull --output .env.local
envlock pull --env production --overwrite

envlock run

Fetches decrypted secrets in memory and runs a command with them injected. Plaintext values are never written to disk.

| Option | Description | Default | | ------------------ | -------------------------------------- | ------------- | | -e, --env <name> | Environment to retrieve variables from | development |

Place -- before your target command so its own arguments pass through correctly.

envlock run -- node index.js
envlock run --env production -- npm start

envlock whoami

Shows which project and environment this directory is currently authenticated to.

envlock whoami

envlock logout

Removes the local session by deleting the credentials stored in .envlock/.

envlock logout

envlock help

Lists all available commands with a short description of each.

envlock help

Security

• Session tokens stored locally in .envlock/credentials.json are saved with owner-only read/write permissions (0o600).
• During login, the server holds an approved token in a pending state and deletes it the moment the CLI retrieves it, so it is never persisted longer than necessary.
• The CLI ensures .envlock/ and .env* patterns exist in your local .gitignore, reducing the chance of secrets being committed by accident.

Contributing

Contributions, issues, and feature requests are welcome.

git clone https://github.com/leyroy/envlock_cli.git
cd envlock_cli
npm install
npm link

npm link makes your local changes available as the global envlock command, so you can test them directly. Open a pull request once your change is ready; for larger changes, opening an issue first to discuss the approach is appreciated.

Support & Links

• Website: envlock.app
• Repository: github.com/leyroy/envlock_cli
• Issues: github.com/leyroy/envlock_cli/issues
• Author: Ley Roy ([email protected])
• License: MIT