A command-line tool for managing cloud secrets (GCP, AWS) with smart change detection and conflict resolution
npm install 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
---
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 |
---
- 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
---
``bash1. Authenticate with Google Cloud
gcloud auth login
$3
`bash
1. Configure AWS credentials
aws configure2. Pull a secret to your local .env file
envister pull my-app my-secret --provider aws --region us-east-13. 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-projectPull latest secrets
envister pull my-secretEdit 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 loginSet 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 configureOr 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-secretOutput:
β οΈ π₯ 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 loginAlso 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 accountVerify project access
gcloud projects describe your-project-idCheck 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-idCheck if the secret exists
gcloud secrets describe your-secret-id --project=your-project-id
`$3
"Unable to locate credentials"
`bash
Configure AWS CLI
aws configureVerify credentials are set
aws sts get-caller-identityOr 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-identityVerify 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-1Check 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 envisterReinstall globally
npm install -g envisterOr use npx
npx envister helpCheck 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 envisterInstall dependencies
npm installRun tests
npm testBuild
npm run buildLink 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 |---
MIT License - see the LICENSE file for details.
---
- npm Package
- GitHub Repository
- Issue Tracker
- Contributing Guide
- GCP Secret Manager
- AWS Secrets Manager
- Google Cloud CLI
- AWS CLI
---
Made with β€οΈ by the Elementor AI Team