Convex CLI always creates .env.local even when environment variables are already set

[delkopiso]

The Convex CLI (convex dev) always creates a .env.local file and adds it to .gitignore, even when the required environment variables (CONVEX_DEPLOYMENT, CONVEX_URL, etc.) are already available in the shell environment.

This behavior is problematic for users who:

• Use tools like direnv with .envrc files
• Manage secrets with external tools (1Password, AWS Secrets Manager, etc.)
• Have environment variables set via CI/CD or container orchestration
• Want to avoid leaving any environment settings in local filesystem

Current Behavior

The CLI creates .env.local in these scenarios even when env vars are already set:

1. convex dev (with CONVEX_DEPLOY_KEY in environment)
2. convex dev --url "$CONVEX_URL" (with URL in environment)
3. convex dev --url "$CONVEX_URL" --admin-key "$CONVEX_ADMIN_KEY" (with both in environment)

Expected Behavior

The CLI should detect existing environment variables and skip file creation when:

• CONVEX_DEPLOYMENT is already set in the shell environment
• The appropriate URL variable (e.g., NEXT_PUBLIC_CONVEX_URL) is already set in the shell environment
• Authentication is available via CONVEX_DEPLOY_KEY or CLI arguments

Reproduction Steps

1. Set environment variables (e.g., via direnv):

   export CONVEX_DEPLOYMENT="dev:amazing-animal-123"
   export CONVEX_URL="https://amazing-animal-123.convex.cloud"
   export NEXT_PUBLIC_CONVEX_URL="https://amazing-animal-123.convex.cloud"
   export CONVEX_DEPLOY_KEY="dev:amazing-animal-123|eyJ..."

2. Run convex dev

3. Observe that .env.local is created despite variables being available

Root Cause Analysis

Looking at the source code in npm-packages/convex/src/cli/lib/envvars.ts:

The envVarWriteConfig function only checks for environment variables in files (.env.local, .env) but not in the shell environment (process.env):

// This only reads from files, not process.env
const existingFileContent = ctx.fs.readUtf8File(envFile);
const config = dotenv.parse(existingFileContent);

Similarly, writeDeploymentEnvVar in deployment.ts only checks file-based environment variables.

[nipunn1313]

This is how the CLI works. If the env local is an issue for you, you can always remove it - but currently this is part of the convex development flow.

[delkopiso]

@nipunn1313 this issue causes the dev flow to be pretty broken if you're working on separate convex projects (for different teams) because convex config (~/.convex/config.json) only saves a single accessToken. If the usage of environment variables was more complete, then there would be no issue. I have a PR that fixes this. Let me know if it'll be welcomed, and I'll open it on the repository.

[nipunn1313]

Sure - send up a PR.

Convex's dev workflow now is set up so you have a single convex config with an access token that represents your account. Your account can be on multiple teams - and that should work fine. If you are logging in with multiple accounts, that's less likely to work well.