CLI Documentation

The Dotenvnest Command Line Interface (CLI) allows you to securely synchronize your .env files between your local development environment and the cloud.

Installation

You can install the CLI globally using npm:

npm install -g dotenvnest

Command Reference

dotenvnest login

Authenticates the CLI securely via your browser. If you are already logged in to the web application, it authenticates automatically.

Example

dotenvnest login
# or
den login

dotenvnest push <project-name>

Encrypts and uploads your local .env file. Pushing a variant like .env.local automatically creates a new project variant (e.g. project-name.local). Smartly detects shared projects automatically.

Example

dotenvnest push my-api-server
# or
den push my-api-server

Options

  • -f, --file <filename>Specify a different file to push (default: .env)
  • --owner <email>Specify the owner email (only required if there is a name collision)

dotenvnest pull <project-name>

Downloads and decrypts the .env file from the specified project. Smartly detects shared projects automatically.

Example

dotenvnest pull my-api-server
# or
den pull my-api-server

Options

  • -f, --file <filename>Specify a different file to output to (default: .env)
  • --owner <email>Specify the owner email (only required if there is a name collision)

dotenvnest find [query]

Searches for projects in your account and projects shared with you, displaying the owner's email for shared projects.

Example

dotenvnest find api
# or
den find api

dotenvnest view <project-name>

Securely prints the environment variables of a project in your terminal without saving a local file.

Example

dotenvnest view my-api-server
# or
den view my-api-server

Options

  • --owner <email>Specify the owner email (if needed for shared projects)

dotenvnest diff <project-name>

Compares your local .env file with the one saved in the cloud, highlighting added, removed, or changed variables.

Example

dotenvnest diff my-api-server
# or
den diff my-api-server

Options

  • -f, --file <filename>Specify a different local file to compare (default: .env)
  • --owner <email>Specify the owner email (if needed for shared projects)

dotenvnest del <project-name>

Permanently deletes a project that you own. Shared projects cannot be deleted.

Example

dotenvnest del my-api-server
# or
den del my-api-server

dotenvnest share <project-name> <emails>

Shares a project with one or more users (comma-separated). The users must have a Dotenvnest account.

Example

dotenvnest share my-api-server "user1@example.com, user2@example.com" --access edit
# or
den share my-api-server "user1@example.com, user2@example.com" --access edit

Options

  • --access <level>Access level: 'read' or 'edit' (default: read)

dotenvnest unshare <project-name> <emails>

Revokes access to a shared project from one or more users (comma-separated).

Example

dotenvnest unshare my-api-server "user1@example.com, user2@example.com"
# or
den unshare my-api-server "user1@example.com, user2@example.com"

dotenvnest leave <project-name>

Leaves a project that someone else has shared with you, removing your access.

Example

dotenvnest leave my-api-server
# or
den leave my-api-server

dotenvnest logout

Logs you out of the CLI and clears your local authentication token.

Example

dotenvnest logout
# or
den logout

CI/CD & Automation

You can easily integrate DotEnvNest into your automated pipelines (like GitHub Actions, GitLab CI, or Vercel) without needing an interactive browser login.

Simply set the DOTENVNEST_TOKEN environment variable in your pipeline settings. The CLI will automatically use it for authentication.

# Example in a CI script
export DOTENVNEST_TOKEN="your_cli_token_here"
npx dotenvnest pull my-api-server

* Tip: You can find your personal CLI token inside the ~/.dotenvnest-config.json file on your computer after logging in locally.

Advanced Usage & Tips

1. Understanding File Variants (-f / --file)

By default, the CLI looks for a file named .env. But what if you have .env.local or .env.production?

If you use the -f flag to push a variant, the CLI automatically maps it to a new project name in the cloud!

# Pushes to project "my-api"
dotenvnest push my-api

# Pushes to a new project named "my-api.local"
dotenvnest push my-api -f .env.local

# Pushes to a new project named "my-api.production"
dotenvnest push my-api -f .env.production

* Tip: When you run dotenvnest find, you will clearly see all your variants listed as separate projects, keeping everything perfectly organized.

2. Handling Name Collisions (--owner)

Imagine you have a project named backend. Your friend also shares their project named backend with you.

If you run dotenvnest pull backend, the CLI gets confused: "Which backend do you want?" It will throw an error asking you to specify the owner. You can fix this by using the --owner flag.

# Pulls YOUR backend project
dotenvnest pull backend

# Pulls your FRIEND'S backend project
dotenvnest pull backend --owner friend@email.com

* Note: The --owner flag works perfectly with push, pull, view, and diff.

3. Project Names with Spaces

If your project name contains spaces (e.g. Developer Saif), you must wrap the name in double quotes when running CLI commands.

Otherwise, the terminal will treat the second word as an invalid argument and throw a "too many arguments" error.

# ❌ This will throw an error
dotenvnest pull Developer Saif

# ✅ This will work perfectly
dotenvnest pull "Developer Saif"

Need help? Feel free to reach out to our support team or check our GitHub repository.