v1.0 Documentation

Envoy Documentation

Learn how to securely manage, version, and synchronize environment variables and configuration files across your team.

Getting Started

What is Envoy

Envoy is a secure version control system for environment variables and configuration files. Inspired by Git, Envoy provides a familiar workflow for developers while adding enterprise-grade security features like AES-256 encryption, access control, and audit logging.

Key Benefits

Git-like workflow that developers already know
End-to-end AES-256 encryption
Team collaboration with granular access control
Complete audit trail of all changes
Web UI for management and monitoring

Installation

Install the Envoy CLI globally using npm:

1$ npm install -g @envoy/cli

Or install locally in your project:

1$ npm install --save-dev @envoy/cli

Verify the installation:

1$ envoy --version

2✓ Envoy CLI v1.0.0

System Requirements

Node.js 16 or higher
npm 7 or higher
Git (for version control features)

Quick Start

Get started with Envoy in 3 simple steps:

1. Initialize your project

1$ envoy init

2✓ Initialized Envoy project

3✓ Created .envoy/config.json

4✓ Connected to remote: https://api.envoy.io

2. Follow and add your .env file

1$ envoy follow .env

2✓ Now tracking .env

4$ envoy add .env

5✓ Staged .env for commit

3. Commit and push

1$ envoy commit -m "Initial environment setup"

2✓ Created commit a1b2c3d

4$ envoy push

5✓ Successfully pushed to origin/main

6✓ Encrypted and stored 12 environment variables

CLI Commands Reference

Envoy provides a comprehensive set of CLI commands for managing your configuration files. All commands follow a Git-like interface for familiarity.

envoy init

Initialize a new Envoy project in the current directory.

1$ envoy init [options]

3Options:

4 --remote <url> Specify remote server URL

5 --project <name> Set project name

6 --force Overwrite existing configuration

Flag	Description	Default
`--remote`	Server URL for syncing	https://api.envoy.io
`--project`	Project name	Directory name
`--force`	Overwrite existing config	false

envoy follow

Start tracking a file or directory for version control.

1$ envoy follow <file|directory> [options]

3Examples:

4 $ envoy follow .env

5 $ envoy follow config/

6 $ envoy follow --all

Important

Only follow files that contain configuration or environment variables. Do not follow sensitive files like private keys or certificates directly.

envoy add

Stage files for the next commit (similar to git add).

1$ envoy add <file|pattern> [options]

3Examples:

4 $ envoy add .env

5 $ envoy add config/*.json

6 $ envoy add --all

7 $ envoy add --interactive

Option	Description
`--all, -A`	Stage all tracked changes
`--interactive, -i`	Interactively choose hunks
`--dry-run`	Show what would be staged

envoy commit

Save staged changes with a descriptive message.

1$ envoy commit -m "message" [options]

3Examples:

4 $ envoy commit -m "Update database config"

5 $ envoy commit -m "Add Redis credentials" --sign

6 $ envoy commit --amend

Option	Description
`-m, --message`	Commit message (required)
`--sign, -S`	Sign commit with GPG
`--amend`	Amend previous commit
`--no-verify`	Skip pre-commit hooks

envoy push

Upload commits to the remote server.

1$ envoy push [remote] [branch] [options]

3Examples:

4 $ envoy push

5 $ envoy push origin main

6 $ envoy push --force

7 $ envoy push --dry-run

Force Push

Using --force overwrites remote history. Use with caution, especially in team environments.

envoy pull

Download the latest changes from the remote server.

1$ envoy pull [remote] [branch] [options]

3Examples:

4 $ envoy pull

5 $ envoy pull origin main

6 $ envoy pull --rebase

7 $ envoy pull --no-merge

envoy status

Check the current state of your working directory.

1$ envoy status

3On branch main

4Your branch is up to date with 'origin/main'.

6Changes to be committed:

7 (use "envoy reset HEAD <file>..." to unstage)

9 modified: .env

10 new file: config/database.json

12Untracked files:

13 (use "envoy follow <file>..." to include)

15 secrets.key

envoy log

View the commit history.

1$ envoy log [options]

3Examples:

4 $ envoy log

5 $ envoy log --oneline

6 $ envoy log --graph

7 $ envoy log -n 10

Option	Description
`--oneline`	Show one commit per line
`--graph`	Show ASCII graph of branches
`-n, --max-count`	Limit number of commits
`--since`	Show commits after date
`--author`	Filter by author

envoy checkout

Restore files to a previous version.

1$ envoy checkout <commit|file> [options]

3Examples:

4 $ envoy checkout HEAD~1

5 $ envoy checkout a1b2c3d .env

6 $ envoy checkout -- .env

7 $ envoy checkout -b feature-branch

Data Loss Risk

Checkout overwrites local files. Consider using envoy stashto save uncommitted changes before checking out.

envoy doctor

Check system health and configuration.

1$ envoy doctor

3Checking Envoy installation...

4✓ CLI version: 1.0.0

5✓ Node.js: 18.17.0

6✓ Git: 2.42.0

8Checking configuration...

9✓ Config file valid

10✓ Remote server reachable

11✓ Authentication token valid

13Checking encryption...

14✓ AES-256 available

15✓ GPG signing available

17All checks passed! ✓

envoy uninstall

Remove the Envoy CLI and clean up configuration.

1$ envoy uninstall [options]

3Options:

4 --global Uninstall global CLI installation

5 --local Remove local project configuration

6 --keep-data Preserve encrypted data on server

Destructive Operation

This will remove the CLI and optionally delete your local configuration. Your encrypted data on the server is preserved unless you explicitly delete it.

Workflow Examples

Basic Workflow

The standard workflow for managing configuration files with Envoy:

Track the file

Start tracking your configuration file

$ envoy follow .env

Stage changes

Add modified files to the staging area

$ envoy add .env

Commit changes

Save changes with a descriptive message

$ envoy commit -m "Add database credentials"

Push to server

Upload encrypted configuration to remote

$ envoy push

Team Collaboration

Workflow for working with a team on shared configuration:

1# 1. Pull latest changes before starting

2$ envoy pull

3✓ Downloaded 3 new commits from origin/main

5# 2. Make your changes and edit .env

6$ nano .env

8# 3. Check what changed

9$ envoy status

10modified: .env

12# 4. Stage, commit, and push

13$ envoy add .env

14$ envoy commit -m "Update API endpoint for staging"

15$ envoy push

17# If there are conflicts:

18$ envoy pull --rebase

19# Resolve conflicts, then:

20$ envoy push

Best Practice

Always pull before pushing to avoid merge conflicts. Use meaningful commit messages so your team understands what changed.

Version Rollback

Restore configuration to a previous state:

1# View commit history

2$ envoy log --oneline

4a1b2c3d Update API endpoint

5b2c3d4e Add Redis config <-- Current HEAD

6c3d4e5f Initial setup

8# Option 1: Revert specific file to previous version

9$ envoy checkout HEAD~1 -- .env

11# Option 2: Restore entire project to specific commit

12$ envoy checkout a1b2c3d

14# Option 3: Create new branch from old commit

15$ envoy checkout -b rollback-branch c3d4e5f

Web UI Guide

Dashboard Overview

The Envoy Web UI provides a centralized interface for managing your projects, users, and configuration:

Overview

Project stats and recent activity

Projects

Manage all your configuration projects

Team

User management and permissions

Audit

Complete activity logs

Project Management

Create and manage configuration projects through the web interface:

Creating a Project

Navigate to Projects in the sidebar
Click Create Project
Enter project name and description
Select encryption settings
Click Create

Project Settings

Setting	Description
Project Name	Unique identifier for the project
Description	Optional details about the project
Encryption	AES-256 encryption toggle
Auto-Backup	Automatic daily backups
Access Level	Private, Team, or Public

File Browser

The file browser allows you to view and manage configuration files:

View contents

Download files

View history

Encryption Note

Files are decrypted in your browser for viewing. The server never sees unencrypted content. Downloaded files maintain their encryption until unlocked.

User Management (Superadmin)

Superadmins have full control over team members and permissions:

User Roles

Role	Permissions
Superadmin	Full access: users, projects, audit logs, system settings
Admin	Project management, user management (except superadmin)
Member	Push/pull, view projects, limited settings access
Viewer	Read-only access to assigned projects

Managing Users

1# Via Web UI:

21. Go to Dashboard → Team Members

32. Click "Invite Member"

43. Enter email and select role

54. Send invitation

7# Via CLI (superadmin only):

8$ envoy admin invite user@example.com --role member

Audit Logs

Comprehensive logging of all activities in your Envoy instance:

Logged Events

File push/pull operations
User login/logout
Permission changes
Project creation/deletion
Failed authentication attempts
Configuration changes

Retention

Audit logs are retained for 90 days by default. Superadmins can export logs or configure extended retention in settings.

Best Practices

File Size Limits

Envoy has the following size limits to ensure optimal performance:

Limit	Value	Notes
Single file	1 GB	Maximum size per configuration file
Total project	10 GB	Combined size of all tracked files
Commit message	1,000 chars	Keep messages concise
History depth	10,000 commits	Per branch

Large Files

Files approaching 1GB may experience slower sync times. Consider splitting large configuration files or using references to external storage.

Security Recommendations

Follow these security best practices when using Envoy:

Enable GPG Signing

Sign all commits to verify authenticity

$ envoy config --global commit.gpgsign true

Use Strong Passphrases

Protect your encryption keys with strong passphrases

Principle of Least Privilege

Grant users only the permissions they need

Regular Audits

Review audit logs weekly for suspicious activity

Team Workflows

Recommended workflows for teams:

Branch Strategy

main # Production configs

├── staging # Staging environment

├── development # Development defaults

└── feature/* # Feature-specific changes

Commit Message Convention

1type(scope): subject

3Types:

4 feat: New configuration

5 fix: Bug fix

6 update: Modify existing config

7 remove: Delete configuration

8 docs: Documentation changes

10Examples:

11 feat(database): add Redis connection

12 fix(api): correct endpoint URL

13 update(staging): increase timeout

Troubleshooting

Common Issues

Authentication Failed

Error: Invalid or expired token

# Solution: Re-authenticate

$ envoy login

# Enter your credentials when prompted

# Or reset credentials

$ envoy logout

$ envoy login

Push Rejected

Error: Remote has newer commits

# Solution: Pull before pushing

$ envoy pull --rebase

$ envoy push

# If conflicts occur:

$ envoy status

# Manually resolve conflicts

$ envoy add <conflicted-file>

$ envoy rebase --continue

File Too Large

Error: File exceeds 1GB limit

# Check file size

$ ls -lh <file>

# Compress if possible

$ gzip <file>

# Or split into smaller files

$ split -b 500M <file> <file>.part

Encryption Errors

Error: Failed to decrypt file

# Verify key is present

$ envoy key list

# Re-import key if needed

$ envoy key import <key-file>

# Check file integrity

$ envoy verify <file>

Debug Mode

Enable debug mode for detailed logging:

1# Enable debug mode

2$ export ENVOY_DEBUG=1

3$ envoy <command>

5# Or use flag

6$ envoy --debug <command>

8# Debug output includes:

9# - HTTP requests/responses

10# - Encryption operations

11# - File I/O details

12# - Timing information

Log Location

Debug logs are written to ~/.envoy/debug.log. Include this file when reporting issues.

Support

Get help with Envoy through these channels:

Community

Join our Discord server

GitHub

Report issues & contribute

Documentation

Read the full docs

Status Page

Check system status

Enterprise Support

Enterprise customers have access to priority email support and dedicated Slack channels. Contact your account manager for details.

Need more help? Contact support

Edit this page•View source