cli

README

DotEnv CLI

Secure environment variable management for modern applications

Installation • Quick Start • Features • Documentation • Contributing

---

🚀 Installation

macOS/Linux

Using Homebrew:

brew tap dotenvcloud/tap
brew install dotenv

Using curl:

curl -sSL https://dotenv.cloud/install.sh | bash

Nightly (bleeding-edge main HEAD)

For staging/dev environments that want the latest unreleased commits, the installer accepts --nightly. The nightly GitHub pre-release is rebuilt on every successful CI on main.

curl -sSL https://dotenv.cloud/install.sh | bash -s -- --nightly

Nightly builds are unsigned for Homebrew/Scoop and not published to the dotenvcloud/homebrew-tap / dotenvcloud/scoop-bucket repositories — those carry stable releases only.

Windows

Using Scoop:

scoop bucket add dotenv https://github.com/dotenvcloud/scoop-bucket
scoop install dotenv

Using PowerShell:

iwr -useb https://dotenv.cloud/install.ps1 | iex

From Source

go install github.com/dotenvcloud/cli@latest

Docker

Run the CLI straight from the official image — no install step, ideal for container-native CI:

docker run --rm \
  -e DOTENV_API_KEY="$DOTENV_API_KEY" \
  -v "$PWD":/work -w /work \
  dotenvcloud/cli:latest pull myproject/production/web --output=.env

Images: dotenvcloud/cli (Docker Hub) and ghcr.io/dotenvcloud/cli (GHCR), multi-arch (amd64/arm64). :latest and :{version} tags arrive with the first stable release; until then use the rolling :main tag. See Docker Integration.

See Installation Guide for more options.

⚡ Quick Start

1. Initialize

dotenv init

This interactive setup will:

• Configure API connection
• Set up authentication
• Configure telemetry preferences

2. Login

dotenv login

Authenticate via browser and select organizations to access. During dotenv init, you'll be offered to login immediately after choosing browser authentication.

3. Pull Secrets

# Pull all secrets for a project
dotenv pull myproject

# Pull specific environment
dotenv pull myproject/production

# Output to file
dotenv pull myproject --output=.env

4. Push Secrets

# Push from file
dotenv push myproject .env

# Push with hierarchy
dotenv push myproject --project=.env.project --target=.env.production

✨ Features

🔐 Security First

• Client-side encryption with AES-256-GCM
• Zero-knowledge architecture - we can't read your secrets
• Secure key storage in local configuration
• API token scoping per organization

🎯 Hierarchical Secrets

• Project-level defaults
• Target-specific overrides (staging, production)
• Environment-specific values
• Smart inheritance - most specific wins

📦 Multiple Formats

• ENV - Standard .env files
• JSON - For modern applications
• YAML - For configuration files
• Shell - Export statements
• Dockerfile - For container builds

🔄 Variable Interpolation

BASE_URL=https://api.example.com
API_ENDPOINT=${BASE_URL}/v1

🚀 CI/CD Ready

• Non-interactive mode for automation
• Exit codes for scripting
• Machine-readable output formats
• Service account support

📊 Optional Telemetry

Help improve DotEnv CLI with anonymous usage data:

• Command usage patterns
• Performance metrics
• Error rates
• Never includes secret values or personal data

🛠️ Commands

dotenv [command] [flags]

Commands:
  init          Initialize configuration
  login         Authenticate with DotEnv
  pull          Pull secrets from DotEnv
  push          Push secrets to DotEnv
  list          List resources (projects, environments)
  export        Export secrets in various formats
  refresh       Refresh API credentials
  update        Update CLI to latest version
  use-context   Switch between organizations
  version       Show version information

Flags:
  -h, --help      Show help
  -v, --version   Show version
  --debug         Enable debug output
  --quiet         Suppress non-error output
  --no-color      Disable colored output

Use "dotenv [command] --help" for more information about a command.

🔧 Configuration

Configuration is stored in ~/.dotenv/config.yaml:

version: "1.0"
telemetry_enabled: true
current_context: production
contexts:
  production:
    api_url: https://api.dotenv.cloud
    organization: acme-corp
  staging:
    api_url: https://api.dotenv.cloud
    organization: acme-corp-staging

See Configuration Guide for details.

📖 Documentation

Guides

• Getting Started
• Configuration
• Encryption
• CI/CD Integration
• Migration Guide

References

• Command Reference
• Config File Reference
• Environment Variables
• File Formats

Examples

• Basic Usage
• Docker Integration
• Kubernetes Secrets
• GitHub Actions
• GitLab CI

🐛 Troubleshooting

Common Issues

Authentication failed

dotenv refresh

Command not found

echo 'export PATH="$HOME/.dotenv/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission denied

chmod +x ~/.dotenv/bin/dotenv

See Troubleshooting Guide for more solutions.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/dotenvcloud/cli.git
cd cli

# Install dependencies
go mod download

# Run tests
make test

# Build locally
make build

Running Tests

# Unit tests
go test ./...

# Integration tests
go test -tags=integration ./tests/integration/...

# Coverage report
make test-coverage

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Cobra and Viper
• Encryption powered by Go's crypto package
• Inspired by the simplicity of .env files

📞 Support

• 📧 Email: support@dotenv.cloud
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues
• 📖 Docs: Documentation

---

Made with ❤️ by the DotEnv team