https://github.com/matipojo/envister
🔐 CLI for managing cloud secrets (GCP, AWS) with smart change detection, conflict resolution, and team collaboration
https://github.com/matipojo/envister
dotenv env environment-variables secrets-manager
Last synced: 4 months ago
JSON representation
🔐 CLI for managing cloud secrets (GCP, AWS) with smart change detection, conflict resolution, and team collaboration
- Host: GitHub
- URL: https://github.com/matipojo/envister
- Owner: matipojo
- License: mit
- Created: 2026-01-26T18:02:19.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-26T21:11:36.000Z (5 months ago)
- Last Synced: 2026-01-27T06:06:59.313Z (5 months ago)
- Topics: dotenv, env, environment-variables, secrets-manager
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/envister
- Size: 263 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Envister
Your Environment Variable Minister
A powerful CLI for managing cloud secrets with intelligent change detection, conflict resolution, and team collaboration support.
Quick Start •
Features •
Installation •
Usage •
Providers •
Conflict Resolution •
Contributing
---
## 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](#-quick-start)
- [Features](#-features)
- [Installation](#-installation)
- [Usage](#-usage)
- [Commands](#commands)
- [Options](#options)
- [Examples](#examples)
- [Providers](#-providers)
- [GCP Secret Manager](#gcp-secret-manager)
- [AWS Secrets Manager](#aws-secrets-manager)
- [How It Works](#-how-it-works)
- [Configuration](#-configuration)
- [Conflict Resolution](#-conflict-resolution)
- [Safety Features](#️-safety-features)
- [Troubleshooting](#-troubleshooting)
- [Comparison with Alternatives](#-comparison-with-alternatives)
- [Roadmap](#-roadmap)
- [Contributing](#-contributing)
- [License](#-license)
---
## 🚀 Quick Start
### GCP Secret Manager
```bash
# 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
```bash
# 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)
```bash
npm install -g envister
```
### Using npx (No Installation)
```bash
npx envister help
```
### Using yarn
```bash
yarn global add envister
```
### Verify Installation
```bash
envister --version
envister help
```
### Prerequisites
Provider
Requirements
GCP
- [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) installed
- Authenticated via `gcloud auth login`
- `Secret Manager Secret Accessor` role (read)
- `Secret Manager Secret Version Adder` role (write)
AWS
- [AWS CLI](https://aws.amazon.com/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 ` | Cloud provider to use | From config |
| `--project ` | Project ID (GCP) or app name (AWS) | From config |
| `--region ` | AWS region | `us-east-1` |
| `--file ` | Target file path | `.env` |
### Examples
#### Basic Workflow
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Grant Secret Manager Secret Accessor role
gcloud projects add-iam-policy-binding my-project \
--member="user:you@example.com" \
--role="roles/secretmanager.secretAccessor"
```
### AWS Secrets Manager
Envister uses the AWS SDK, inheriting credentials from the AWS CLI or environment variables.
#### Setup
```bash
# 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
```json
{
"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
```json
{
"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`:
```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
```bash
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
```bash
# 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
```bash
envister push my-secret .env.conflict-patch
```
---
## 🛡️ Safety Features
### Confirmation Prompts
Every destructive operation requires confirmation:
```bash
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:
```bash
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:
```bash
# 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
"Failed to get access token"
```bash
# Re-authenticate with Google Cloud
gcloud auth login
# Also set application default credentials (for SDK)
gcloud auth application-default login
```
"Permission denied" or "403 Forbidden"
```bash
# 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
```
"Secret not found"
```bash
# 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
"Unable to locate credentials"
```bash
# 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
```
"Access Denied" or "UnauthorizedAccess"
```bash
# 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
```
"Secret not found" (AWS)
```bash
# 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
"Command not found: envister"
```bash
# 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
```
Conflict patch file issues
```bash
# 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](https://github.com/matipojo/envister/issues/new?template=feature_request.md)!
---
## 🤝 Contributing
We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.
### Quick Start for Contributors
```bash
# 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](LICENSE) file for details.
---
## 🔗 Links
- [npm Package](https://www.npmjs.com/package/envister)
- [GitHub Repository](https://github.com/matipojo/envister)
- [Issue Tracker](https://github.com/matipojo/envister/issues)
- [Contributing Guide](CONTRIBUTING.md)
### Cloud Provider Documentation
- [GCP Secret Manager](https://cloud.google.com/secret-manager/docs)
- [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/)
- [Google Cloud CLI](https://cloud.google.com/sdk/docs/install)
- [AWS CLI](https://aws.amazon.com/cli/)
---
Made with ❤️ by the Elementor AI Team