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
- 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

$3

``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
`

$3

`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

$3

| 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 |

$3

- 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

$3

`bash
npm install -g envister
`

$3

`bash
npx envister help
`

$3

`bash
yarn global add envister
`

$3

`bash
envister --version
envister help
`

$3
















Provider	Requirements
GCP	- Google Cloud CLI installed - Authenticated via gcloud auth login - Secret Manager Secret Accessor role (read) - Secret Manager Secret Version Adder role (write)
AWS	- AWS CLI installed - Configured via aws configure - secretsmanager:GetSecretValue permission (read) - secretsmanager:PutSecretValue permission (write) - secretsmanager:ListSecrets permission (list)

---

📖 Usage

$3

| 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 |

$3

| 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 |

$3

#### 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

$3

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"
`

$3

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 │
│ │
└─────────────────────────────────────────────────────────────┘
`

$3

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

$3

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.

$3

`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..."
}
}
`

$3

| 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 |

$3

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.

$3

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

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

$3

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) │
│ │
└─────────────────────────────────────────────────────────────────┘
`

$3

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

$3

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):

`

$3

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

`

$3

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...
`

$3

> 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

$3

"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
`

$3

"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
`

$3

"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

$3

- [ ] 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

$3

- [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.

$3

`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
`

$3

| 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

$3

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

---

Made with ❤️ by the Elementor AI Team

⭐ Star us on GitHub