convex-env-sync

A CLI tool that syncs environment variables with Convex using a locally defined .env.convex file. This saves you the hassle of having to go to the dashboard to configure environment variables. On startup, it performs an initial sync, then watches the file for changes and periodically polls the Convex deployment for remote updates.

It uses the official Convex CLI internally to read, set, and remove environment variables.

This tool intentionally does not attempt to provide type-safe access to environment variables inside your Convex functions. If you’re looking for that functionality, use convex-env by @bentsignal (both tools can be used together).

Guide

npx convex-env-sync

Adding Variables

To add a variable to Convex, define it in your .env.convex file:

API_KEY=sk-123

The variable will be added to Convex when the file is saved.

Deleting Variables

To delete a variable from Convex, set its value to __DELETE__:

# This will delete API_KEY from Convex
API_KEY=__DELETE__

The variable will be removed from Convex and deleted from the local file on save.

Note

If the deployment and the local file have the same variables with different values, the local file takes precedence. This is because it is intended for use with dev deployments, in which you are usually the only user. To sync down the dev deployment version, simply delete the .env.convex file and run npx convex-env-sync.

Setup in package.json

You will usually want to run this alongside your Convex dev server:

{
  "scripts": {
    "dev:convex": "npx convex-env-sync & convex dev"
  }
}

Options

| Option | Description | | ------------------ | --------------------------------------------------- | | --file <path> | Path to env file (default: .env.convex) | | --once | Run a single sync and exit | | --no-write-back | Prevent updating the local file from remote changes | | --poll <seconds> | Polling interval for remote changes (default: 300) | | -h, --help | Show help message |

Requirements

• Node.js 18+
• Convex CLI configured in the project (convex dev must work)
• Can be run via bunx, npx, or pnpm dlx

License

MIT