Skip to content

Docs

Using Envbyte

Install it, share a project with your team, and keep everyone's .env files in sync. Every command here runs in a terminal, inside the folder that holds your app's .env.

Install

Pick whichever suits you. They all install the same envbyte command.

macOS

Download envbyte.pkg and double-click it. It works on Apple silicon and Intel Macs and asks for your password, because it installs into /usr/local/bin. Or, in Terminal:

curl -fsSL https://envbyte.trackedge.in/install.sh | sh
If macOS says it can't verify the developer, open System Settings → Privacy & Security, scroll down, and click Open Anyway next to envbyte.pkg.

Windows

Download envbyte.msi and double-click it. It installs for your user only, so it needs no administrator rights. Or, in PowerShell or Command Prompt:

powershell -c "irm https://envbyte.trackedge.in/install.ps1 | iex"
If Windows shows "Windows protected your PC", click More info, then Run anyway.

Linux

curl -fsSL https://envbyte.trackedge.in/install.sh | sh

npm or Cargo

npm install -g envbyte
# or build it from source (Rust 1.88 or newer)
cargo install envbyte

Then open a new terminal and check it works:

envbyte --version

Create an account

envbyte register

It asks for your email, a username and a password, then emails you a verification code. Paste the code in and you're signed in. The code lasts two hours; if it expires or never arrives, check your spam folder, then run envbyte verify to get a new one.

Other account commands:

CommandWhat it does
envbyte loginSign in on this computer
envbyte whoamiShow who you're signed in as
envbyte logoutSign out on this computer
envbyte reset-passwordEmail yourself a code and choose a new password
Already use Envbyte on another computer? Read A second computer before you run envbyte login on a new one.

Your first project

Go to the folder that holds your app's .env file, then:

envbyte create my-app
envbyte push -m "first version"

create links the folder to a new project and adds Envbyte's files and your .env files to .gitignore, so no secret ends up in git. Project names only have to be unique within your own account.

push encrypts the file on your computer and uploads it. The server stores it but can't read it. If the folder has more than one .env file (.env, .env.production, ...), Envbyte asks which one, or you can name it:

envbyte push -f .env.production -m "add Stripe keys"

envbyte status shows which project the folder is linked to, who you're signed in as, and whether everything is in order.

The first time you use Envbyte, it creates a personal key for this computer at ~/.envbyte-identity. It's what lets this computer open your projects. Back it up like an SSH key, and never share it.

Invite your team

  1. Your teammate installs Envbyte and runs envbyte register. They need to be signed in at least once before you can invite them.
  2. You invite them by email:
envbyte add priya@company.com
  1. They get an email with a one-time code. In their copy of the app's folder, they run envbyte init, paste the code, and then envbyte pull.
envbyte init
envbyte pull

That's all. Nobody sends a password or a key over chat. The invitation works only for the account it was sent to, so forwarding the email to someone else gives them nothing. It expires after 24 hours and can be used once.

New people join as members. See Roles to change that. Each teammate runs envbyte init in their own copy of the project, because the link file isn't committed to git.

Push and pull

Push uploads your local file as a new version. Pull downloads the latest version.

envbyte push -m "rotate database password"
envbyte pull

Both take -f <file> to pick a file without being asked. Each push records a message, so history explains itself later.

If your local file has no changes of its own, pull simply updates it. If it does, pull doesn't throw them away: it offers to merge them with the server's version (see the next section), to replace them, or to stop.

When two people edit at once

Envbyte remembers which version of each file you last pulled or pushed. If a teammate pushed after that, your push isn't allowed to quietly overwrite their change. Envbyte merges the two instead, one variable at a time:

  • A variable only you changed keeps your value.
  • A variable only they changed takes theirs.
  • Variables either of you added or removed are added or removed.
  • A variable you both changed, to different values, is the only thing you're asked about.
$ envbyte push -m "new Redis host"
! .env changed on the server since this checkout last synced it.
--- Merging .env
  - API_KEY changed on the server
  - REDIS_URL changed by you

! DB_PASSWORD was changed both by you and on the server.
Which value should win?
  [1] keep yours         s3c...42 (24 chars)
  [2] take the server's  pr0...9f (24 chars)
Select (1-2): 1
Save the merged .env and push it? [y/N]: y
OK Pushed.

The merged file is saved to your folder and pushed, so you and your teammates end up with the same thing. Envbyte only shows the start and end of each value, never the whole secret.

To make one side win outright instead:

# replace the server's copy with yours
envbyte push --force
# replace your copy with the server's
envbyte pull --force
Merging keeps your file's layout and comments. A change someone made only to a comment isn't carried over. In a script, with no one to answer, a merge without clashes goes ahead on its own and a real clash stops with an error naming the variables.
This needs Envbyte 0.5 or newer on every computer. Older versions overwrite whatever is on the server, so ask your team to update.

History and rollback

Every push is kept as a version. To see them, and to make an older one current again for everyone:

envbyte logs --remote
envbyte rollback --address <commit>
envbyte pull

Rollback asks before it changes anything. Teammates get the restored version on their next pull.

Local snapshots

You can also save a snapshot of .env in this folder only, without touching the server, and restore it later:

envbyte commit "before the migration"
envbyte logs
envbyte rollback --local <id>

Snapshots are stored encrypted, so restoring one needs you to be signed in.

Roles

OwnerAdminMemberViewer
Pull files, see history and membersYesYesYesYes
Push, roll backYesYesYesNo
Invite, remove, rotate the key, read the audit logYesYesNoNo
Make someone an admin, or remove an adminYesNoNoNo

The person who creates a project is its owner. Find people's IDs with envbyte members, then:

envbyte members
envbyte role <user-id> viewer
envbyte audit

envbyte audit lists who pushed, rolled back, invited, removed and rotated, with dates.

Removing someone

envbyte members
envbyte remove <user-id>
envbyte rotate

remove cuts their access to the project straight away. rotate then gives the project a new key, re-locks every file with it, and hands it only to the people who remain, so anything the person kept from before can't open what you push next. It shows exactly what it will do and asks first; rotate -y skips the question.

The rest of the team doesn't need to do anything. Their next pull or push picks up the new key.

Rotating protects what you push from now on. The person who left may have seen the actual values, so also change the passwords and API keys that matter, and push the new ones.

A second computer

Your access lives in the personal key on your first computer. To use the same account on another one, take that key with you:

  1. On the computer you already use, run envbyte identity export. It prints your key. Treat it like a password.
  2. On the new computer, store it in the ENVBYTE_IDENTITY_KEY environment variable, for example in your shell profile on macOS and Linux, or in your user environment variables on Windows. Then open a new terminal and run envbyte login.
  3. Copy the .envbyte file from the project folder on your old computer into the same folder on the new one, then run envbyte pull. That file only says which project the folder belongs to; it contains no keys.
# macOS and Linux: add this line to ~/.zshrc or ~/.bashrc
export ENVBYTE_IDENTITY_KEY="<the key you exported>"
If you sign in on a new computer without doing this, Envbyte creates a new key for your account. The new computer can't open your existing projects, and the old one loses access at the next key rotation. To recover, ask an admin of each project to run envbyte rotate; your new computer can then read the current files.

Commands

CommandWhat it does
registerCreate an account
verifySend a new verification code and finish signing up
loginSign in on this computer
logoutSign out on this computer
whoamiShow the signed-in account
reset-passwordChoose a new password
create <name>Start a project in this folder
initJoin a project you were invited to
projectsList the projects you can reach
push [-m msg] [-f file] [--force]Encrypt and upload a .env file
pull [-f file] [--force]Download the latest version
commit <message>Save a local snapshot of .env
logsList local snapshots
logs --remoteList every pushed version
rollback --address <commit>Make an older version current for everyone
rollback --local <id>Restore a local snapshot into .env
add <email>Invite someone
membersList members, their roles and IDs
role <user-id> <role>Make someone an admin, member or viewer
remove <user-id>Remove someone from the project
rotate [-y]Give the project a new key, for current members only
statusShow what this folder is linked to and whether it works
auditShow the project's audit log
identityShow this computer's key fingerprint
identity exportPrint this computer's key, for another computer

Every command starts with envbyte, and envbyte help <command> explains its options.

Settings

Envbyte reads these environment variables. None are needed for normal use.

VariableWhat it's for
ENVBYTE_SERVERUse your own Envbyte server instead of the hosted one
ENVBYTE_IDENTITY_KEYYour personal key, given directly instead of read from a file
ENVBYTE_IDENTITY_FILEWhere your personal key is stored (default ~/.envbyte-identity)

Files on your computer

FileWhat it holds
.envbyteWhich project this folder is linked to, and which versions you last synced
.envbyte-logsYour local snapshots, encrypted
~/.envbyte-authYour sign-in on this computer
~/.envbyte-identityThis computer's personal key. Back it up, never share it

The ones in your project folder, and your .env files, are added to .gitignore for you. On macOS and Linux only your user can read them.

Self-hosting

The hosted service works out of the box. To run your own server instead, you need Docker on a machine your team can reach over HTTPS:

git clone https://github.com/NYLONXD/EnvByte_CLI
cd EnvByte_CLI
# set POSTGRES_PASSWORD and ENVBYTE_JWT_SECRET in .env
cp .env.example .env
docker compose up -d
curl http://localhost:3030/health/ready

Before your team uses it:

  • Put it behind HTTPS. Envbyte refuses to send sign-ins over plain HTTP to anything but localhost.
  • Set ENVBYTE_ENV=production and configure real email with ENVBYTE_EMAIL_MODE=smtp and the SMTP_* settings, so verification codes and invitations are delivered.
  • Behind a load balancer or reverse proxy, set ENVBYTE_TRUSTED_PROXY_HOPS to the number of proxies (usually 1), or everyone shares one rate limit.

Then everyone points their CLI at it:

export ENVBYTE_SERVER=https://envbyte.your-company.com

Accounts on your server are separate from the hosted service. Every setting is described in the server guide.

Troubleshooting

"envbyte: command not found"

Open a new terminal; the installer added Envbyte to your PATH, and terminals that were already open don't know yet.

The first command is slow, or times out

The hosted server sleeps when nobody has used it for a while, and can take up to a minute to wake up. Run the command again.

"that account has not published an identity key yet"

The person you're inviting hasn't signed in with a current version of Envbyte. Ask them to run envbyte login, then invite them again.

"No .envbyte file found"

You're not in a linked folder. Go to your project's folder, or link it with envbyte create or envbyte init.

"... encrypted with project key version 1, but the project is on version 2"

The project's key was rotated and you don't have the new one. Run envbyte status to confirm, then ask an admin to run envbyte rotate, which hands the current key to every member.

"Both you and the server changed ..."

You pushed from a script, and a teammate changed the same variable. Run the push in a terminal to choose, or use --force to keep yours. See When two people edit at once.

You lost your personal key

Sign in again with envbyte login, which creates a new key, then ask an admin of each project to run envbyte rotate. Versions pushed before that may stay unreadable to you.

Something else? Open an issue on GitHub.

Uninstall

Installed withTo remove it
envbyte.pkg (macOS)sudo rm /usr/local/bin/envbyte && sudo pkgutil --forget in.trackedge.envbyte
envbyte.msi (Windows)Settings → Apps → Envbyte → Uninstall
install.shrm -rf ~/.envbyte
install.ps1Delete the .envbyte folder in your user folder
npmnpm uninstall -g envbyte
Cargocargo uninstall envbyte

Uninstalling keeps your sign-in and personal key, in case you come back. If you're done for good, run envbyte logout first, then delete ~/.envbyte-identity.