Getting Started

From download to first sync in under 5 minutes.

1Download & Install

Grab the latest release from GitHub Releases:

  • macOS — Universal .dmg (Apple Silicon + Intel)
  • Windows — x64 .exe installer

First launch on macOS?

Env Butler is unsigned (we keep it free instead of paying $99/yr for a certificate). Bypass Gatekeeper:

xattr -d com.apple.quarantine /Applications/Env\ Butler.app

Or right-click the app → Open → Open.

2Set Up Supabase

Env Butler stores encrypted blobs in your own Supabase instance. You own the data — we never see it.

  1. Create a free project at supabase.com
  2. Open the SQL Editor in your Supabase dashboard
  3. Run the migration below:
CREATE TABLE IF NOT EXISTS vault (
  id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  project_slug   TEXT NOT NULL UNIQUE,
  encrypted_blob TEXT NOT NULL,
  plaintext_hash TEXT NOT NULL,
  metadata       JSONB,
  created_at     TIMESTAMPTZ DEFAULT NOW(),
  updated_at     TIMESTAMPTZ DEFAULT NOW()
);

ALTER TABLE vault ENABLE ROW LEVEL SECURITY;

CREATE POLICY "allow_all_for_anon" ON vault
  FOR ALL USING (true) WITH CHECK (true);

CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER vault_updated_at
  BEFORE UPDATE ON vault
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at();
  1. Copy your Project URL and Service Role Key from Settings → API

3Configure Env Butler

  1. Open Env Butler and go to Settings
  2. Paste your Supabase URL and Service Role Key
  3. Add a project — pick a folder and give it a slug (e.g., my-api)
  4. Generate your 24-word mnemonic — this IS your Master Key (BIP39 standard). It never leaves your machine. Save it offline (paper, password manager, safe deposit box).

4Push & Pull

Push

Scans your project for .env* files, shows a preview of what will be synced (file names, variable counts, sensitive key warnings), encrypts everything, and uploads to Supabase.

Pull

Downloads encrypted data, checks for conflicts (hash comparison), decrypts, and writes files to your project — only after you approve.

5CLI (Alternative)

Prefer the terminal? Install the CLI and use the same features:

cargo install --path crates/cli

env-butler init
env-butler config --url https://xxx.supabase.co --key eyJ...
env-butler push
env-butler pull

6Team Sharing

Share vault access with team members using encrypted invite tokens. No auth server needed.

Owner

env-butler team invite
# Share the .envbutler-team file
# + passphrase via Slack/AirDrop

Team Member

env-butler team join token.envbutler-team
# Enter passphrase → done
# Can now push/pull

7CI/CD Integration

Pull .env files in GitHub Actions with a service token:

# Generate token (one-time, interactive)
env-butler ci generate-token
# → Copy output to GitHub Secrets as ENVBUTLER_TOKEN

# In your workflow:
- name: Pull env files
  run: env-butler ci pull --force
  env:
    ENVBUTLER_TOKEN: ${{ secrets.ENVBUTLER_TOKEN }}

Where config lives

~/.env-butler/
  projects.json    # Your projects (slugs, paths, sync hashes)
  config.json      # Supabase URL + service role key + sync folder