DotenvHub CLI

Official command-line interface for DotenvHub - Secure environment variable management with team collaboration.

Features

• 🔐 Secure Authentication - Browser-based login with personal access tokens
• 📁 Project Management - List and access your projects from the command line
• ⬇️ Variable Download - Pull environment variables in multiple formats
• 🔓 Decryption Support - Decrypt encrypted variables with master password
• 💳 Subscription Awareness - Real-time plan limits and usage tracking
• 🎯 Smart Project Resolution - Use project names or IDs interchangeably
• 👥 Team Collaboration - Access shared projects with role-based permissions
• 🛡️ Security First - Encrypted storage and secure token management
• 🌍 Cross-Platform - Works on Windows, macOS, and Linux

Installation

Install globally using npm:

npm install -g dotenvhub-cli

Or using yarn:

yarn global add dotenvhub-cli

Quick Start

1. Authenticate

dotenvhub login

This will open your browser to authenticate with your DotenvHub account and generate a personal access token.

2. List Your Projects

dotenvhub projects

3. Download Environment Variables

# Using project name
dotenvhub pull my-project production

# Using project ID (more reliable for automation)
dotenvhub pull 550e8400-e29b-41d4-a716-446655440000 production

# With decryption (will prompt for master password)
dotenvhub pull my-project production --decrypt

This downloads variables from the production environment to a .env file.

Commands

Authentication

# Interactive browser-based authentication
dotenvhub login

# Direct token authentication (for CI/CD)
dotenvhub login --token dh_your_token_here

# Check authentication status
dotenvhub whoami

# Logout and remove stored credentials
dotenvhub logout

Project Management

# List all accessible projects
dotenvhub projects

# List projects in JSON format
dotenvhub projects --format json

# Alias for projects command
dotenvhub ls

Subscription Management

# Check subscription status and limits
dotenvhub subscription

# Alias for subscription command
dotenvhub plan

Variable Management

# Download variables to .env file (default)
dotenvhub pull my-project production

# Use project ID instead of name (recommended for CI/CD)
dotenvhub pull 550e8400-e29b-41d4-a716-446655440000 production

# Specify output file
dotenvhub pull my-project staging -o .env.staging

# Different output formats
dotenvhub pull my-project dev --format json -o config.json
dotenvhub pull my-project prod --format yaml -o config.yaml

# Force overwrite existing files
dotenvhub pull my-project test --force

# Decrypt variables with interactive password prompt
dotenvhub pull my-project production --decrypt

# Decrypt with password parameter (for automation)
dotenvhub pull my-project production --master-password "your-password" --decrypt

# Project names with spaces (use quotes)
dotenvhub pull "My Web App" production --decrypt

Subscription Plans & Limits

DotenvHub CLI is subscription-aware and enforces plan limits:

Starter Plan (Free)

• ✅ 1 project maximum
• ✅ 2 collaborators maximum
• ✅ 1,000 API calls/month
• ✅ Community support

Pro Plan ($5/month)

• ✅ Unlimited projects
• ✅ Unlimited collaborators
• ✅ Unlimited API calls
• ✅ Email support
• ✅ Advanced features

Check your current plan:

dotenvhub subscription

The CLI will warn you when approaching limits and suggest upgrades when needed.

Project Resolution

The CLI supports both project names and project IDs:

# View your projects with IDs
dotenvhub projects
# Output: My Web App (ID: 550e8400-e29b-41d4-a716-446655440000)

# Both of these work:
dotenvhub pull "My Web App" production    # Using name
dotenvhub pull 550e8400-e29b-41d4-a716-446655440000 production  # Using UUID (recommended for CI/CD)

Benefits of using Project UUIDs:

• ✅ Faster: No API lookup required
• ✅ Reliable: Immune to project name changes
• ✅ CI/CD Friendly: Works great in automation

Configuration

Environment Variables

You can configure the CLI using environment variables:

# Custom API endpoint (default: https://api.dotenvhub.com)
export DOTENVHUB_API_URL=https://your-custom-api.com

# Custom authentication URL (default: https://dotenvhub.com/cli-auth)
export DOTENVHUB_AUTH_URL=https://your-custom-auth.com/cli-auth

# Enable debug mode
export DEBUG=1

Configuration Directory

The CLI stores credentials in ~/.dotenvhub/credentials.json. This file is automatically created with restricted permissions (0600) for security.

Output Formats

.env Format (default)

dotenvhub pull my-project production
# Creates .env file with:
# DATABASE_URL=postgresql://...
# API_KEY=sk_...
# JWT_SECRET=...

JSON Format

dotenvhub pull my-project production --format json -o config.json
# Creates config.json with:
# {
#   "DATABASE_URL": "postgresql://...",
#   "API_KEY": "sk_...",
#   "JWT_SECRET": "..."
# }

YAML Format

dotenvhub pull my-project production --format yaml -o config.yaml
# Creates config.yaml with:
# DATABASE_URL: "postgresql://..."
# API_KEY: "sk_..."
# JWT_SECRET: "..."

CI/CD Integration

For automated environments, use project IDs and direct token authentication:

# GitHub Actions example
- name: Pull environment variables
  run: |
    npm install -g dotenvhub-cli
    dotenvhub login --token ${{ secrets.DOTENVHUB_TOKEN }}
    # Use project ID for reliability
    dotenvhub pull 550e8400-e29b-41d4-a716-446655440000 production
    # Or with decryption for encrypted variables
    dotenvhub pull 550e8400-e29b-41d4-a716-446655440000 production --master-password ${{ secrets.MASTER_PASSWORD }} --decrypt
    
# Use the downloaded variables
- name: Deploy
  env:
    DATABASE_URL: ${{ env.DATABASE_URL }}
  run: npm run deploy

Docker Example

# Dockerfile
FROM node:18-alpine

# Install CLI
RUN npm install -g dotenvhub-cli

# Pull variables at build time
ARG DOTENVHUB_TOKEN
ARG MASTER_PASSWORD
RUN dotenvhub login --token $DOTENVHUB_TOKEN && \
    dotenvhub pull 550e8400-e29b-41d4-a716-446655440000 production --master-password $MASTER_PASSWORD --decrypt

COPY . .
CMD ["npm", "start"]

Best Practices for CI/CD

1. Use Project IDs: More reliable than names
2. Store Tokens Securely: Use your CI platform's secret management
3. Check Subscription: Use dotenvhub subscription to verify limits
4. Handle Errors: CLI exits with non-zero codes on failure

Security

• Token Storage: Credentials are stored in ~/.dotenvhub/credentials.json with restricted file permissions
• HTTPS Only: All API communication uses HTTPS encryption
• Token Validation: Tokens are validated before storage and use
• No Logging: Sensitive data is never logged or cached
• Automatic Cleanup: Logout command securely removes all stored credentials

Error Handling

The CLI provides clear error messages and suggestions:

# Authentication errors
❌ Authentication failed. Please run `dotenvhub login` to re-authenticate.
❌ Invalid token provided

# Permission errors  
❌ Permission denied. You may not have access to this resource.

# Project resolution errors
❌ Project 'my-project' not found. Use 'dotenvhub projects' to list available projects.
❌ Environment 'staging' not found in project 'my-project'.

# Subscription limit errors
⚠️  Project limit reached. Upgrade to Pro for unlimited projects.
❌ Subscription limit exceeded: Maximum 1 projects allowed on Starter plan.

# Decryption errors
❌ Decryption failed: Invalid master password or corrupted data
❌ Master password required for encrypted variables. Use --decrypt flag.

# General errors
⚠️  No variables found for this project/environment
❌ File '.env' already exists. Use --force to overwrite.

Development

Local Development

# Clone and install dependencies
git clone https://github.com/dotenvhub/dotenvhub-cli.git
cd dotenvhub-cli
npm install

# Link for global development
npm link

# Test commands
dotenvhub --help

Running Tests

npm test

Environment Setup

Create .env file for development:

DOTENVHUB_API_URL=http://localhost:3000/api
DOTENVHUB_AUTH_URL=http://localhost:5173/cli-auth
DEBUG=1

Support

• 📖 Documentation: https://docs.dotenvhub.com
• 🐛 Issues: GitHub Issues
• 💬 Community: Discord Community
• ✉️ Email: [email protected]

License

MIT © DotenvHub

Made with ❤️ by the DotenvHub team