Package Exports

dotenvhub-cli
dotenvhub-cli/bin/dotenvhub.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (dotenvhub-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Use Project IDs: More reliable than names
Store Tokens Securely: Use your CI platform's secret management
Check Subscription: Use dotenvhub subscription to verify limits
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: support@dotenvhub.com

License

Made with ❤️ by the DotenvHub team