dotenvx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dotenvx CLI

dotenvx is a secure dotenv — from the creator of

dotenv

. It provides encrypted environment variables, cross-platform

run

injection, and multi-environment support.

Key capabilities:

```
dotenvx run
```
— inject env vars into any command, any language
```
dotenvx encrypt
```
— encrypt
```
.env
```
files with public-key cryptography (secp256k1)
```
dotenvx set
```
/
```
get
```
— manage individual env vars
```
dotenvx decrypt
```
— decrypt
```
.env
```
files back to plaintext
Multi-environment support via
```
-f
```
flag and
```
DOTENV_PRIVATE_KEY_*
```
convention

dotenvx是一款安全的dotenv工具——由

dotenv

的开发者打造。它提供加密环境变量、跨平台

run

注入以及多环境支持。

核心功能：

```
dotenvx run
```
—— 将.env文件中的环境变量注入任意命令、任意语言的进程
```
dotenvx encrypt
```
—— 使用公钥密码学（secp256k1）加密.env文件
```
dotenvx set
```
/
```
get
```
—— 管理单个环境变量
```
dotenvx decrypt
```
—— 将.env文件解密回明文
通过-f flag和
```
DOTENV_PRIVATE_KEY_*
```
命名约定支持多环境

Installation

安装

undefined

undefined

npm (local to project)

npm（项目本地安装）

npm install @dotenvx/dotenvx --save

global installs

全局安装

curl -sfS https://dotenvx.sh | sh # curl brew install dotenvx/brew/dotenvx # brew winget install dotenvx # windows docker run -it --rm -v $(pwd):/app dotenv/dotenvx help # docker


For Node.js, also usable as a library:
```js
require('@dotenvx/dotenvx').config()
// or: import '@dotenvx/dotenvx/config'

curl -sfS https://dotenvx.sh | sh # curl方式 brew install dotenvx/brew/dotenvx # brew方式 winget install dotenvx # Windows系统 docker run -it --rm -v $(pwd):/app dotenv/dotenvx help # Docker方式


对于Node.js，也可作为库使用：
```js
require('@dotenvx/dotenvx').config()
// 或：import '@dotenvx/dotenvx/config'

Core Commands

核心命令

dotenvx run

dotenvx run

Inject environment variables from

.env

files into any process. This is the primary command.

dotenvx run -- <command>

Flags:

Flag	Description
`-f <file>`	Specify env file(s). Repeatable. Default: `.env`
`--env KEY=value`	Set inline env var
`--overload`	Later files/values override earlier ones (default: first wins)
`--strict`	Exit code 1 on any error (missing file, decrypt failure)
`--ignore=ERROR_CODE`	Ignore specific errors (e.g., `MISSING_ENV_FILE` )
`--convention=nextjs\|flow`	Load files using Next.js or dotenv-flow convention
`-fk <path>`	Specify path to `.env.keys` file (useful for monorepos)
`--quiet`	Suppress all output except errors
`--verbose`	Verbose logging
`--debug`	Debug-level logging
`--log-level=<level>`	Set log level: `error, warn, info, verbose, debug, silly`

Examples:

undefined

将.env文件中的环境变量注入任意进程。这是最主要的命令。

dotenvx run -- <command>

参数：

参数	描述
`-f <file>`	指定.env文件，可重复使用。默认值： `.env`
`--env KEY=value`	设置内联环境变量
`--overload`	后续文件/值覆盖之前的（默认：先出现的优先级更高）
`--strict`	出现任何错误时以退出码1终止（文件缺失、解密失败等）
`--ignore=ERROR_CODE`	忽略特定错误（例如： `MISSING_ENV_FILE` ）
`--convention=nextjs\|flow`	按照Next.js或dotenv-flow的约定加载文件
`-fk <path>`	指定 `.env.keys` 文件的路径（适用于monorepo场景）
`--quiet`	除错误外抑制所有输出
`--verbose`	详细日志输出
`--debug`	调试级日志输出
`--log-level=<level>`	设置日志级别： `error, warn, info, verbose, debug, silly`

示例：

undefined

Basic usage

基础用法

dotenvx run -- node index.js

Specific env file

指定环境文件

dotenvx run -f .env.production -- node index.js

Multiple env files (first file's values win by default)

多个环境文件（默认第一个文件的值优先级更高）

dotenvx run -f .env.local -f .env -- node index.js

Override: last file wins

覆盖模式：最后一个文件的值优先级更高

dotenvx run -f .env.local -f .env --overload -- node index.js

Inline env var (overrides file values)

内联环境变量（覆盖文件中的值）

dotenvx run --env HELLO=String -f .env -- node index.js

Any language works

支持任意语言

dotenvx run -- python3 app.py dotenvx run -- ruby index.rb dotenvx run -- go run main.go dotenvx run -- cargo run dotenvx run -- php artisan serve dotenvx run -- next dev

Shell expansion (use subshell to prevent premature expansion)

Shell展开（使用子shell避免提前展开）

dotenvx run --env="HELLO=World" -- sh -c 'echo Hello $HELLO'

Strict mode for CI

CI环境下的严格模式

dotenvx run -f .env.ci --strict -- node build.js


**Precedence rules:**
- By default, env vars already set in the shell take precedence over `.env` file values
- With multiple `-f` files, the first file's value wins (historic dotenv behavior)
- `--overload` reverses this: later files override earlier ones
- `--env` flag values take precedence over file values

**Variable expansion and interpolation:**

dotenvx supports `${VAR}` expansion, default values, alternate values, and command substitution inside `.env` files:

```ini

dotenvx run -f .env.ci --strict -- node build.js


**优先级规则：**
- 默认情况下，Shell中已设置的环境变量优先级高于.env文件中的值
- 使用多个`-f`文件时，第一个文件的值优先级更高（dotenv的历史行为）
- `--overload`会反转此规则：后续文件覆盖之前的
- `--env`参数设置的值优先级高于文件中的值

**变量展开与插值：**

dotenvx支持.env文件中的`${VAR}`展开、默认值、替代值以及命令替换：

```ini

Variable expansion

变量展开

USERNAME="admin" DATABASE_URL="postgres://${USERNAME}@localhost/mydb"

Default values (use fallback if unset/empty)

默认值（若变量未设置/为空则使用回退值）

DB_HOST=${DB_HOST:-localhost} DB_PORT=${DB_PORT:-5432}

Alternate values (use alternate if variable IS set)

替代值（若变量已设置则使用替代值）

DEBUG_MODE=${NODE_ENV:+false}

Command substitution

命令替换

WHOAMI="$(whoami)"


**Multiline values** are supported — wrap in double quotes:
```ini
CERT="-----BEGIN CERTIFICATE-----
MIIB...
-----END CERTIFICATE-----"

WHOAMI="$(whoami)"


**多行值**同样支持——用双引号包裹：
```ini
CERT="-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----"

Important: What dotenvx Does NOT Have

重要说明：dotenvx 不具备的功能

Do NOT hallucinate these — they do not exist:

❌
```
dotenvx keys
```
— use
```
dotenvx keypair
```
instead
❌
```
dotenvx status
```
— no such command
❌
```
dotenvx rotate
```
— to rotate, use
```
dotenvx set
```
to update values, or decrypt → delete .env.keys → re-encrypt
❌
```
--env-name
```
flag — does not exist
❌
```
.env.vault
```
files — dotenvx encrypts in place, not to a separate vault file
❌
```
DOTENVX_PRIVATE_KEY
```
— the correct env var is
```
DOTENV_PRIVATE_KEY
```
(no X in the middle)
❌
```
pip install dotenvx
```
— there is no Python package; dotenvx is a CLI tool that wraps any language

❌

dotenvx.load_dotenv()

— no Python API; use

dotenvx run -- python app.py

at the CLI level

请勿编造以下不存在的功能：

❌
```
dotenvx keys
```
—— 请使用
```
dotenvx keypair
```
替代
❌
```
dotenvx status
```
—— 无此命令
❌
```
dotenvx rotate
```
—— 如需轮换密钥，使用
```
dotenvx set
```
更新值，或执行解密→删除.env.keys→重新加密
❌
```
--env-name
```
参数 —— 不存在
❌
```
.env.vault
```
文件 —— dotenvx是原地加密，不会生成单独的vault文件
❌
```
DOTENVX_PRIVATE_KEY
```
—— 正确的环境变量是
```
DOTENV_PRIVATE_KEY
```
（中间没有X）
❌
```
pip install dotenvx
```
—— 不存在Python包；dotenvx是一款可包裹任意语言的CLI工具

❌

dotenvx.load_dotenv()

—— 无Python API；请在CLI层面使用

dotenvx run -- python app.py

dotenvx encrypt

dotenvx encrypt

Encrypt

.env

file(s) in place. Generates a

DOTENV_PUBLIC_KEY

(added to the

.env

file) and a

DOTENV_PRIVATE_KEY

(saved to

.env.keys

dotenvx encrypt                     # encrypts .env
dotenvx encrypt -f .env.production  # encrypts specific file
dotenvx encrypt --stdout            # output to stdout instead of in-place

After encryption:

```
.env
```
contains encrypted values +
```
DOTENV_PUBLIC_KEY
```
```
.env.keys
```
contains
```
DOTENV_PRIVATE_KEY
```
(keep this secret, never commit it)
The encrypted
```
.env
```
is safe to commit to version control

原地加密.env文件。生成

DOTENV_PUBLIC_KEY

（添加到.env文件中）和

DOTENV_PRIVATE_KEY

（保存到.env.keys中）。

dotenvx encrypt                     # 加密.env
dotenvx encrypt -f .env.production  # 加密指定文件
dotenvx encrypt --stdout            # 输出到标准输出而非原地修改

加密完成后：

```
.env
```
包含加密后的值 +
```
DOTENV_PUBLIC_KEY
```
```
.env.keys
```
包含
```
DOTENV_PRIVATE_KEY
```
（请妥善保密，切勿提交到版本控制）
加密后的.env可安全提交到版本控制

dotenvx decrypt

dotenvx decrypt

Decrypt an encrypted

.env

file back to plaintext.

dotenvx decrypt                     # decrypts .env
dotenvx decrypt -f .env.production  # decrypts specific file
dotenvx decrypt --stdout            # output to stdout

Requires the private key to be available (via

.env.keys

file or

DOTENV_PRIVATE_KEY*

env var).

将加密的.env文件解密回明文。

dotenvx decrypt                     # 解密.env
dotenvx decrypt -f .env.production  # 解密指定文件
dotenvx decrypt --stdout            # 输出到标准输出

需要可用的私钥（通过.env.keys文件或

DOTENV_PRIVATE_KEY_*

环境变量提供）。

dotenvx set

dotenvx set

Set an individual environment variable in a

.env

file. Creates the file if it doesn't exist. If the file is encrypted, re-encrypts automatically.

dotenvx set KEY value                       # set in .env
dotenvx set KEY value -f .env.production    # set in specific file
dotenvx set KEY "multi word value"          # quoted values
dotenvx set KEY value -fk .env.keys -f apps/app1/.env  # monorepo

在.env文件中设置单个环境变量。若文件不存在则创建。若文件已加密，会自动重新加密。

dotenvx set KEY value                       # 在.env中设置
dotenvx set KEY value -f .env.production    # 在指定文件中设置
dotenvx set KEY "multi word value"          # 带空格的值需加引号
dotenvx set KEY value -fk .env.keys -f apps/app1/.env  # monorepo场景

dotenvx get

dotenvx get

Retrieve a single environment variable's value.

dotenvx get HELLO                          # from .env
dotenvx get HELLO -f .env.production       # from specific file
dotenvx get HELLO --env HELLO=Override     # from --env string
dotenvx get HELLO --overload               # with overload semantics
dotenvx get HELLO --strict                 # exit 1 if key missing
dotenvx get HELLO --convention=nextjs      # with convention
dotenvx get HELLO -fk .env.keys -f app/.env  # monorepo

Get all as JSON:

dotenvx get                    # all vars from .env as JSON
dotenvx get -f .env.production # all vars from specific file
dotenvx get --all              # include DOTENV_PUBLIC_KEY
dotenvx get --format shell     # output as KEY=value lines

获取单个环境变量的值。

dotenvx get HELLO                          # 从.env获取
dotenvx get HELLO -f .env.production       # 从指定文件获取
dotenvx get HELLO --env HELLO=Override     # 从--env参数获取
dotenvx get HELLO --overload               # 使用覆盖语义
dotenvx get HELLO --strict                 # 若密钥缺失则以退出码1终止
dotenvx get HELLO --convention=nextjs      # 遵循指定约定
dotenvx get HELLO -fk .env.keys -f app/.env  # monorepo场景

以JSON格式获取所有变量：

dotenvx get                    # 以JSON格式获取.env中的所有变量
dotenvx get -f .env.production # 以JSON格式获取指定文件中的所有变量
dotenvx get --all              # 包含DOTENV_PUBLIC_KEY
dotenvx get --format shell     # 以KEY=value格式输出

dotenvx keypair

dotenvx keypair

Output the public/private keypair for an encrypted

.env

file.

dotenvx keypair                              # all keypairs as JSON
dotenvx keypair DOTENV_PRIVATE_KEY           # just the private key
dotenvx keypair -f .env.production           # for specific file
dotenvx keypair DOTENV_PRIVATE_KEY_PRODUCTION -f .env.production

输出加密.env文件对应的公钥/私钥对。

dotenvx keypair                              # 以JSON格式输出所有密钥对
dotenvx keypair DOTENV_PRIVATE_KEY           # 仅输出私钥
dotenvx keypair -f .env.production           # 输出指定文件对应的密钥对
dotenvx keypair DOTENV_PRIVATE_KEY_PRODUCTION -f .env.production

Encryption Workflow

加密工作流

Initial Setup

初始设置

undefined

undefined

1. Create your .env

1. 创建.env文件

echo "DATABASE_URL=postgres://localhost/mydb" > .env echo "API_KEY=sk-secret123" >> .env

2. Encrypt it

2. 加密文件

dotenvx encrypt

✔ encrypted (.env)

✔ 已加密 (.env)

Creates .env.keys with your private key

创建包含私钥的.env.keys文件

3. Commit .env (encrypted, safe), do NOT commit .env.keys

3. 提交.env（已加密，安全），请勿提交.env.keys

echo ".env.keys" >> .gitignore git add .env .gitignore git commit -m "add encrypted env"

undefined

echo ".env.keys" >> .gitignore git add .env .gitignore git commit -m "add encrypted env"

undefined

Multi-Environment Encryption

多环境加密

Each environment gets its own keypair. The naming convention is automatic:

undefined

每个环境都有自己的密钥对，命名约定是自动的：

undefined

Encrypt each environment

加密各个环境的文件

dotenvx encrypt -f .env.production dotenvx encrypt -f .env.staging dotenvx encrypt -f .env.ci

Each creates a corresponding private key in .env.keys:

每个操作会在.env.keys中创建对应的私钥：

DOTENV_PRIVATE_KEY_PRODUCTION="..."

DOTENV_PRIVATE_KEY_STAGING="..."

DOTENV_PRIVATE_KEY_CI="..."

undefined

undefined

Runtime Decryption

运行时解密

Set the appropriate

DOTENV_PRIVATE_KEY_*

env var, and

dotenvx run

decrypts automatically:

undefined

设置对应的

DOTENV_PRIVATE_KEY_*

环境变量，

dotenvx run

会自动解密：

undefined

The private key suffix matches the file suffix

私钥后缀与文件后缀匹配

DOTENV_PRIVATE_KEY="key" dotenvx run -- node app.js # decrypts .env DOTENV_PRIVATE_KEY_PRODUCTION="key" dotenvx run -- node app.js # decrypts .env.production DOTENV_PRIVATE_KEY_CI="key" dotenvx run -- node app.js # decrypts .env.ci

DOTENV_PRIVATE_KEY="key" dotenvx run -- node app.js # 解密.env DOTENV_PRIVATE_KEY_PRODUCTION="key" dotenvx run -- node app.js # 解密.env.production DOTENV_PRIVATE_KEY_CI="key" dotenvx run -- node app.js # 解密.env.ci

Combine multiple

组合多个私钥

DOTENV_PRIVATE_KEY="k1" DOTENV_PRIVATE_KEY_PRODUCTION="k2" dotenvx run -- node app.js

Comma-separated keys for monorepos (same environment, different apps)

逗号分隔的密钥适用于monorepo（同一环境，不同应用）

DOTENV_PRIVATE_KEY_CI="key1,key2" dotenvx run -f app1/.env.ci -f app2/.env.ci -- node app.js

undefined

DOTENV_PRIVATE_KEY_CI="key1,key2" dotenvx run -f app1/.env.ci -f app2/.env.ci -- node app.js

undefined

CI/CD Integration

CI/CD集成

yaml

undefined

yaml

undefined

GitHub Actions example

GitHub Actions示例

name: deploy on: [push] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: curl -fsS https://dotenvx.sh/install.sh | sh - run: dotenvx run -- node build.js env: DOTENV_PRIVATE_KEY_PRODUCTION: ${{ secrets.DOTENV_PRIVATE_KEY_PRODUCTION }}

---

---

Conventions

约定

--convention=nextjs

--convention=nextjs

Loads files in Next.js priority order:

```
.env.$(NODE_ENV).local
```
```
.env.local
```
```
.env.$(NODE_ENV)
```
```
.env
```

dotenvx run --convention=nextjs -- next dev

按照Next.js的优先级顺序加载文件：

```
.env.$(NODE_ENV).local
```
```
.env.local
```
```
.env.$(NODE_ENV)
```
```
.env
```

dotenvx run --convention=nextjs -- next dev

--convention=flow

--convention=flow

Loads files in dotenv-flow priority order. Uses

DOTENV_ENV

NODE_ENV

DOTENV_ENV=development dotenvx run --convention=flow -- node app.js

按照dotenv-flow的优先级顺序加载文件，使用

DOTENV_ENV

或

NODE_ENV

：

DOTENV_ENV=development dotenvx run --convention=flow -- node app.js

Monorepo Support

Monorepo支持

Use

-fk

to specify a shared

.env.keys

path:

undefined

使用

-fk

指定共享的

.env.keys

路径：

undefined

Set values for different apps

为不同应用设置值

dotenvx set HELLO app1 -fk .env.keys -f apps/app1/.env dotenvx set HELLO app2 -fk .env.keys -f apps/app2/.env

Run with shared keys

使用共享密钥运行

dotenvx run -fk .env.keys -f apps/app1/.env -- node apps/app1/index.js

Get values

获取值

dotenvx get HELLO -fk .env.keys -f apps/app1/.env

---

dotenvx get HELLO -fk .env.keys -f apps/app1/.env

---

Docker

dockerfile

FROM node:latest
RUN curl -fsS https://dotenvx.sh/install.sh | sh
COPY . .
CMD ["dotenvx", "run", "--", "node", "index.js"]

Or run directly:

docker run -it --rm -v $(pwd):/app dotenv/dotenvx run -- node index.js

dockerfile

FROM node:latest
RUN curl -fsS https://dotenvx.sh/install.sh | sh
COPY . .
CMD ["dotenvx", "run", "--", "node", "index.js"]

或直接运行：

docker run -it --rm -v $(pwd):/app dotenv/dotenvx run -- node index.js

Common Patterns

常见模式

Add a new secret to an encrypted file:

dotenvx set NEW_SECRET "value" -f .env.production

为加密文件添加新密钥：

dotenvx set NEW_SECRET "value" -f .env.production

Automatically re-encrypts

会自动重新加密


**Rotate a value:**
```sh
dotenvx set API_KEY "new-key-value" -f .env.production

View decrypted values without running a command:

dotenvx get -f .env.production           # needs private key available
dotenvx get API_KEY -f .env.production   # single value

Convert existing plaintext .env to encrypted:

dotenvx encrypt -f .env.production


**轮换密钥值：**
```sh
dotenvx set API_KEY "new-key-value" -f .env.production

不运行命令查看解密后的值：

dotenvx get -f .env.production           # 需要可用的私钥
dotenvx get API_KEY -f .env.production   # 查看单个值

将现有明文.env转换为加密格式：

dotenvx encrypt -f .env.production

Done. Commit the encrypted .env.production, store .env.keys privately.

完成。提交加密后的.env.production，妥善存储.env.keys。


**Suppress dotenvx output in scripts:**
```sh
dotenvx run --quiet -- ./my-script.sh

Fail CI on missing/broken env:

dotenvx run -f .env.ci --strict -- npm test


**在脚本中抑制dotenvx的输出：**
```sh
dotenvx run --quiet -- ./my-script.sh

在CI环境中因环境问题失败：

dotenvx run -f .env.ci --strict -- npm test

Gitignore Recommendations

扩展命令 (

dotenvx ext

)

gitignore

undefined

用于管理dotenvx工作流的实用命令：

dotenvx ext genexample                  # 从.env生成.env.example
dotenvx ext genexample -f .env.production  # 从指定文件生成
dotenvx ext gitignore                   # 将.env.keys追加到.gitignore
dotenvx ext ls                          # 列出项目中所有.env文件
dotenvx ext ls -f .env.production       # 检查指定文件
dotenvx ext settings                    # 查看当前dotenvx设置

Never commit private keys

—

.env.keys

—

Encrypted .env files ARE safe to commit

—

!.env

—

!.env.production

—

!.env.staging

—

undefined

—

Troubleshooting

—

MISSING_ENV_FILE
— the specified
```
.env
```
file doesn't exist. Create it or use
```
--ignore=MISSING_ENV_FILE
```
.
MISSING_KEY
— the requested key isn't in the
```
.env
```
file.
Decryption fails — ensure the correct
```
DOTENV_PRIVATE_KEY_*
```
is set. The suffix must match the file suffix (e.g.,
```
_PRODUCTION
```
for
```
.env.production
```
).
Deno + encrypt — don't use
```
deno run npm:@dotenvx/dotenvx encrypt
```
. Deno has incomplete cipher support. Install dotenvx as a binary instead.
Shell expanding
$VARS
prematurely — use a subshell:
```
dotenvx run -- sh -c 'echo $MY_VAR'
```

—

Extension Commands (

dotenvx ext

)

—

Utility commands for managing dotenvx workflows:

dotenvx ext genexample                  # generate .env.example from .env
dotenvx ext genexample -f .env.production  # from specific file
dotenvx ext gitignore                   # append .env.keys to .gitignore
dotenvx ext ls                          # list all .env files in project
dotenvx ext ls -f .env.production       # check specific file
dotenvx ext settings                    # view current dotenvx settings

—