Why Envister?

Managing environment variables across teams is painful. Secrets get out of sync, changes get overwritten, and there's no easy way to see what changed. Envister solves this by treating your cloud secrets like code—with version tracking, change detection, and merge conflict resolution.

| Without Envister | With Envister | |-----------------|---------------| | ❌ Manual copy-paste from cloud console | ✅ One command to sync | | ❌ No visibility into what changed | ✅ Clear diff before any change | | ❌ Overwrites without warning | ✅ Confirmation prompts for safety | | ❌ Team conflicts go unnoticed | ✅ Three-way merge with conflict detection | | ❌ Switch between cloud UIs | ✅ Unified CLI for GCP & AWS |

📖 Table of Contents

• Quick Start
• Features
• Installation
• Usage
  • Commands
  • Options
  • Examples
• Providers
  • GCP Secret Manager
  • AWS Secrets Manager
• How It Works
• Configuration
• Conflict Resolution
• Safety Features
• Troubleshooting
• Comparison with Alternatives
• Roadmap
• Contributing
• License

🚀 Quick Start

GCP Secret Manager

# 1. Authenticate with Google Cloud
gcloud auth login

# 2. Pull a secret to your local .env file
envister pull my-project my-secret --provider gcp

# 3. Make changes to your .env file, then push
envister push

AWS Secrets Manager

# 1. Configure AWS credentials
aws configure

# 2. Pull a secret to your local .env file
envister pull my-app my-secret --provider aws --region us-east-1

# 3. Make changes to your .env file, then push
envister push

That's it! Configuration is saved to .envister.status.json. Subsequent commands use your saved settings automatically.

✨ Features

Core Capabilities

| Feature | Description | |---------|-------------| | 🔐 Multi-Cloud Support | Works with both GCP Secret Manager and AWS Secrets Manager | | 📥 Smart Pull | Downloads secrets with overwrite protection and change preview | | 📤 Smart Push | Uploads with automatic change detection and confirmation | | 🔥 Conflict Resolution | Git-style three-way merge for team collaboration | | 📋 Secret Discovery | List and browse secrets in your projects | | 🔍 Change Detection | Visual diff showing exactly what will change | | ⚠️ Safety First | Always confirms before destructive operations | | 🌍 Cross-Platform | Works on macOS, Linux, and Windows |

What Sets Envister Apart

• Version Tracking: Remembers which version you pulled, enabling conflict detection
• Three-Way Merge: When conflicts occur, shows base, remote, and local versions
• Patch Files: Generates Git-style conflict markers for manual resolution
• Native Security: Uses your existing cloud CLI credentials—no new auth to manage

📦 Installation

Using npm (Recommended)

npm install -g envister

Using npx (No Installation)

npx envister help

Using yarn

yarn global add envister

Verify Installation

envister --version
envister help

Prerequisites

• Google Cloud CLI installed
• Authenticated via gcloud auth login
• Secret Manager Secret Accessor role (read)
• Secret Manager Secret Version Adder role (write)

• AWS CLI installed
• Configured via aws configure
• secretsmanager:GetSecretValue permission (read)
• secretsmanager:PutSecretValue permission (write)
• secretsmanager:ListSecrets permission (list)

📖 Usage

Commands

| Command | Description | Example | |---------|-------------|---------| | envister init | Interactive setup wizard | envister init | | envister pull [secret] | Download secret to local .env file | envister pull my-secret | | envister push [secret] | Upload local .env to cloud secret | envister push my-secret | | envister list | List all secrets in project | envister list | | envister config | Show current configuration | envister config | | envister help | Display help information | envister help |

Options

| Option | Description | Default | |--------|-------------|---------| | --provider <gcp\|aws> | Cloud provider to use | From config | | --project <id> | Project ID (GCP) or app name (AWS) | From config | | --region <name> | AWS region | us-east-1 | | --file <path> | Target file path | .env |

Examples

Basic Workflow

# Initialize (first time only)
envister init --provider gcp --project my-project

# Pull latest secrets
envister pull my-secret

# Edit your .env file locally
# ...

# Push changes back
envister push my-secret

Working with Multiple Secrets

# Pull different secrets to different files
envister pull production-config --file .env.production
envister pull staging-config --file .env.staging
envister pull development-config --file .env.development

Project Override

# Use a different project for one command
envister pull other-project other-secret
envister pull --project other-project other-secret  # Same result

🌐 Providers

GCP Secret Manager

Envister uses the gcloud CLI under the hood, inheriting your existing authentication and permissions.

Setup

# Install Google Cloud CLI
# https://cloud.google.com/sdk/docs/install

# Authenticate
gcloud auth login

# Set default project (optional)
gcloud config set project my-project

Required Permissions

| Permission | Required For | |------------|--------------| | secretmanager.secrets.list | envister list | | secretmanager.versions.access | envister pull | | secretmanager.versions.add | envister push |

Example IAM Role

# Grant Secret Manager Secret Accessor role
gcloud projects add-iam-policy-binding my-project \
  --member="user:[email protected]" \
  --role="roles/secretmanager.secretAccessor"

AWS Secrets Manager

Envister uses the AWS SDK, inheriting credentials from the AWS CLI or environment variables.

Setup

# Install AWS CLI
# https://aws.amazon.com/cli/

# Configure credentials
aws configure

# Or use environment variables
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_REGION=us-east-1

Required Permissions

| Permission | Required For | |------------|--------------| | secretsmanager:ListSecrets | envister list | | secretsmanager:GetSecretValue | envister pull | | secretsmanager:PutSecretValue | envister push |

Example IAM Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:ListSecrets",
        "secretsmanager:GetSecretValue",
        "secretsmanager:PutSecretValue"
      ],
      "Resource": "*"
    }
  ]
}

⚙️ How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        Envister Workflow                         │
└─────────────────────────────────────────────────────────────────┘

  ┌──────────┐         ┌──────────────┐         ┌──────────────┐
  │  Cloud   │         │   Envister   │         │    Local     │
  │  Secret  │◄───────►│     CLI      │◄───────►│   .env File  │
  │ Manager  │         │              │         │              │
  └──────────┘         └──────────────┘         └──────────────┘
       │                      │                        │
       │                      ▼                        │
       │               ┌──────────────┐                │
       │               │   Version    │                │
       │               │   Tracker    │                │
       │               │  (.status)   │                │
       │               └──────────────┘                │
       │                      │                        │
       ▼                      ▼                        ▼
  ┌─────────────────────────────────────────────────────────────┐
  │                                                             │
  │  PULL: Cloud → Compare → Confirm → Write .env + Track       │
  │                                                             │
  │  PUSH: .env → Detect Changes → Check Conflicts → Upload     │
  │                                                             │
  └─────────────────────────────────────────────────────────────┘

Pull Flow

1. Fetch secret content from cloud provider
2. Compare with existing local file (if any)
3. Display changes as a visual diff
4. Confirm with user before overwriting
5. Write to local file
6. Track version metadata for conflict detection

Push Flow

1. Read local .env file
2. Fetch current remote version
3. Detect changes between local and remote
4. Check for conflicts (if version changed since pull)
5. Confirm with user showing exact changes
6. Upload new version

🔧 Configuration

Envister stores configuration in .envister.status.json in your working directory.

Configuration File Structure

{
  "provider": "gcp",
  "projectId": "my-project",
  "secretId": "my-secret",
  "lastPull": {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "secretVersion": "projects/my-project/secrets/my-secret/versions/5",
    "contentHash": "abc123..."
  }
}

Configuration Options

| Field | Description | Required | |-------|-------------|----------| | provider | Cloud provider (gcp or aws) | Yes | | projectId | GCP project ID or AWS app identifier | Yes | | secretId | Name of the secret | No (can be passed as argument) | | region | AWS region (AWS only) | No (defaults to us-east-1) | | lastPull | Metadata from last pull (auto-managed) | Auto |

Git Integration

Add to your .gitignore:

# Envister
.envister.status.json
.env
*.conflict-patch

Note: The status file contains version metadata, not secrets. However, it's recommended to gitignore it to avoid confusion.

🔥 Conflict Resolution

When multiple team members modify the same secret, Envister detects and helps resolve conflicts.

How Conflict Detection Works

Timeline:
─────────────────────────────────────────────────────────►

  You pull v3         Alice pushes v4      You try to push
      │                     │                    │
      ▼                     ▼                    ▼
  ┌───────┐            ┌───────┐            ┌───────┐
  │  v3   │            │  v4   │            │ Your  │
  │ (base)│            │(remote)│           │changes│
  └───────┘            └───────┘            └───────┘
                                                 │
                                                 ▼
                                        🔥 CONFLICT DETECTED!

Three-Way Merge Analysis

When a conflict is detected, Envister analyzes all three versions:

┌─────────────────────────────────────────────────────────────────┐
│                    Three-Way Merge Analysis                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  BASE (v3)              REMOTE (v4)           LOCAL (yours)     │
│  ──────────             ────────────          ─────────────     │
│  API_KEY=abc            API_KEY=abc           API_KEY=abc       │
│  DB_HOST=old            DB_HOST=new  ◄─────   DB_HOST=mine      │
│  TIMEOUT=30             TIMEOUT=60   ◄─────   TIMEOUT=30        │
│                         NEW_VAR=xyz  ◄─────                     │
│  OLD_VAR=123                                  OLD_VAR=123       │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  ✅ Auto-mergeable:                                             │
│     + NEW_VAR (added remotely)                                  │
│     ~ TIMEOUT (modified remotely, no local change)              │
│     - OLD_VAR (deleted remotely)                                │
│                                                                 │
│  ❌ Conflicts:                                                  │
│     🔥 DB_HOST (both modified differently)                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Conflict Resolution Workflow

1. Detection: Envister alerts you to the conflict

envister push my-secret

# Output:
# ⚠️  🔥 CONFLICT DETECTED!
# 📝 The secret has been modified since your last pull.
#
# Base version: projects/my-project/secrets/my-secret/versions/3
# Remote version: projects/my-project/secrets/my-secret/versions/4

2. Analysis: Review the three-way merge summary

3. Patch Generation: A patch file is created with Git-style markers

# Generated: .env.conflict-patch

# Conflict for: DB_HOST
<<<<<<< LOCAL
DB_HOST=my-local-value
||||||| BASE
DB_HOST=original-value
=======
DB_HOST=remote-value
>>>>>>> REMOTE

4. Resolution: Edit the patch file to resolve conflicts

5. Push: Upload the resolved configuration

envister push my-secret .env.conflict-patch

🛡️ Safety Features

Confirmation Prompts

Every destructive operation requires confirmation:

envister push my-secret

# 📋 Changes Summary:
# ==================
# 🆕 New keys (1):
#    + NEW_FEATURE_FLAG=enabled
#
# 🔄 Updated keys (1):
#    ~ DATABASE_URL
#      - postgres://old-host/db
#      + postgres://new-host/db
#
# ❓ Do you want to continue with these changes? (y/N):

Change Preview

See exactly what will change before any operation:

envister pull my-secret

# ⚠️  File .env already exists with different content.
#
# 📋 Pulling will make the following changes to your local file:
# ==================
# 🆕 New keys (2):
#    + API_KEY=secret_value_123
#    + ANOTHER_VAR=another_value
#
# 🔄 Updated keys (1):
#    ~ EXISTING_KEY
#      - old_value
#      + new_value
#
# 🗑️ Deleted keys (1):
#    - REMOVED_KEY

Value Protection

Sensitive values are truncated in output:

# Long values are truncated for safety
DATABASE_URL=postgres://user:pass@host:5432/...
API_KEY=sk-proj-abc123...

Native Security Model

Important: Envister does not implement its own authentication or authorization. It uses your existing cloud CLI credentials (gcloud for GCP, aws for AWS), inheriting their security model, permissions, and audit logging.

🆘 Troubleshooting

GCP Issues

# Re-authenticate with Google Cloud
gcloud auth login

# Also set application default credentials (for SDK)
gcloud auth application-default login

# Check your current identity
gcloud config get-value account

# Verify project access
gcloud projects describe your-project-id

# Check your IAM roles
gcloud projects get-iam-policy your-project-id \
  --flatten="bindings[].members" \
  --filter="bindings.members:$(gcloud config get-value account)"

# Request the necessary role
# Ask your admin to grant: roles/secretmanager.secretAccessor

# List all secrets in the project
gcloud secrets list --project=your-project-id

# Check if the secret exists
gcloud secrets describe your-secret-id --project=your-project-id

AWS Issues

# Configure AWS CLI
aws configure

# Verify credentials are set
aws sts get-caller-identity

# Or use environment variables
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_REGION=us-east-1

# Check your identity
aws sts get-caller-identity

# Verify you have the required permissions
# Required: secretsmanager:GetSecretValue, secretsmanager:PutSecretValue

# Test with AWS CLI
aws secretsmanager list-secrets --region us-east-1

# List all secrets
aws secretsmanager list-secrets --region us-east-1

# Check specific secret
aws secretsmanager describe-secret --secret-id your-secret-id --region us-east-1

General Issues

# Check if installed
npm list -g envister

# Reinstall globally
npm install -g envister

# Or use npx
npx envister help

# Check npm global bin path
npm config get prefix
# Add {prefix}/bin to your PATH if needed

# If the patch file has syntax errors, ensure you:
# 1. Removed all lines starting with #
# 2. Removed all conflict markers (<<<<<<< ======= >>>>>>>)
# 3. Each line follows KEY=value format

# Validate your file
cat your-file.env | grep -E '^[A-Z_]+=.+$'

📊 Comparison with Alternatives

| Feature | Envister | dotenv-vault | chamber | Manual | |---------|----------|--------------|---------|--------| | GCP Support | ✅ | ❌ | ❌ | ✅ | | AWS Support | ✅ | ✅ | ✅ | ✅ | | Change Detection | ✅ | ❌ | ❌ | ❌ | | Conflict Resolution | ✅ | ❌ | ❌ | ❌ | | Version Tracking | ✅ | ✅ | ❌ | ❌ | | Native Auth | ✅ | ❌ | ✅ | ✅ | | No Account Required | ✅ | ❌ | ✅ | ✅ | | Team Collaboration | ✅ | ✅ | ❌ | ❌ | | Visual Diff | ✅ | ❌ | ❌ | ❌ | | Free & Open Source | ✅ | Freemium | ✅ | ✅ |

🗺️ Roadmap

Planned Features

• [ ] Azure Key Vault support - Third major cloud provider
• [ ] HashiCorp Vault support - Self-hosted secrets management
• [ ] Secret rotation helpers - Automated rotation workflows
• [ ] Team sharing - Share configurations across team members
• [ ] CI/CD integration - GitHub Actions, GitLab CI templates
• [ ] Secret templates - Generate secrets from templates
• [ ] Audit log viewing - View who changed what and when

Recently Completed

• [x] AWS Secrets Manager support
• [x] Three-way merge conflict resolution
• [x] Version tracking for conflict detection
• [x] Interactive confirmation prompts

Have a feature request? Open an issue!

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Quick Start for Contributors

# Clone the repository
git clone https://github.com/matipojo/envister.git
cd envister

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Link for local testing
npm link
envister help

Development Commands

| Command | Description | |---------|-------------| | npm test | Run all tests | | npm run test:watch | Run tests in watch mode | | npm run test:coverage | Run tests with coverage report | | npm run lint | Check for linting errors | | npm run lint:fix | Auto-fix linting errors | | npm run format | Format code with Prettier | | npm run build | Compile TypeScript |

📄 License

MIT License - see the LICENSE file for details.

🔗 Links

• npm Package
• GitHub Repository
• Issue Tracker
• Contributing Guide

Cloud Provider Documentation

• GCP Secret Manager
• AWS Secrets Manager
• Google Cloud CLI
• AWS CLI