Skip .env.local creation when environment variables exist in process.env

[delkopiso]

Summary

Fixes issue where Convex CLI always creates .env.local files even when required environment variables (CONVEX_DEPLOYMENT, CONVEX_URL, etc.) are already available in the shell environment. This was problematic for users who manage secrets with external tools, use direnv, or deploy in CI/CD environments.

This PR contains two commits that together resolve the issue:

1. Skip .env.local creation when environment variables exist - Modified the core logic to check process.env before creating .env.local files
2. Fix misleading log messages - Updated logging to only show file creation messages when files are actually written to disk

Problem Solved

Root Cause: The CLI only checked for environment variables in files (.env.local, .env) but not in the shell environment (process.env).

Before:

• CLI always created .env.local even when CONVEX_DEPLOYMENT was set via direnv, CI/CD, or shell exports
• Users saw misleading "Saved deployment details to .env.local" messages even when no file was needed
• Problematic for users who avoid leaving environment settings in local filesystem

After:

• CLI detects existing environment variables in process.env and skips file creation
• Users only see file creation messages when files are actually written
• Respects users' preferred environment management workflows

Fixes #191

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[Copilot]

Pull Request Overview

This PR improves the Convex CLI's environment variable handling by checking process.env before creating .env.local files, preventing unnecessary file creation when environment variables are already available in the shell environment.

Key changes include:

• Enhanced writeConvexUrlToEnvFile to check process.env for existing environment variables before file creation
• Updated writeDeploymentEnvVar to skip file operations when CONVEX_DEPLOYMENT is already set in the environment
• Added comprehensive test coverage for the new behavior

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
npm-packages/convex/src/cli/lib/envvars.ts	Added process.env check to skip .env.local creation when variables exist
npm-packages/convex/src/cli/lib/deployment.ts	Added early return when CONVEX_DEPLOYMENT exists in process.env
npm-packages/convex/src/cli/lib/envvars.test.ts	New test file covering process.env behavior scenarios
npm-packages/convex/src/cli/lib/deployment.test.ts	Added test for deployment env var skip behavior

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[delkopiso]

@nipunn1313 could you take at look at this PR for me? I'd appreciate any feedback

[thomasballinger]

@delkopiso these values aren't secret, and they're needed by the frontend to know where to connect to. What's your use case, what's the flow you'd like to support here?

[thomasballinger]

I'll wait to hear what you're trying to support, if I were guessing I'd say

• check out CONVEX_DEPLOY_KEY
• are you creating apps that dont' have a frontend, or deploy the frontend seprately? If so, what would help you here?
• is this for self-hosted cases where the deployment name and URL are constant, and you don't want to enable creating new local dev deployments? If so, say more about that

[delkopiso]

@thomasballinger my primary usecase is working on separate projects concurrently. I first ran into issues because the access token setup assumes a single account for all projects. Ultimately, there are two things I want to solve for:

• Not having to manage variables (secret or not) in more than one way. My projects aren't using .env files.
• Being able to context switch across projects without need to redo the cli auth flow.

I documented in #191 that setting CONVEX_DEPLOY_KEY didn't prevent the dev flow from trying to write the files.

[thomasballinger]

Hm, re multiple accounts that's just not something we're anticipating; can you add your single account to multiple teams instead? It sounds like you want to be logged into multiple accounts and have which account is used depend on the project; nothing like this planned but if there's a good reason you need multiple accounts it sounds like that's something to think about for the future.

Re the first bullet

Not having to manage variables (secret or not) in more than one way. My projects aren't using .env files.

Every time someone checks your project repo out and runs convex, they get a new CONVEX_URL. It sounds like you want to take this environment variable and move it to another system. You have another way of telling the frontend/client/website what URL to use to talk to the backend.

Are you saying that if the correct environment variables exist in process.env (and they match what the CLI would have generated) then they shouldn't be written? We could add an option for that. I don't want to silently not write .env.local just because the environment variables are present, because the more important thing is that the website have them available.

I totally agree re CONVEX_DEPLOYMENT, that shouldn't be in .env.local; that's just a convenient place to put it to remember which project a repo checkout is associated with.

Two potential alternative proposals here:

1. How about a dev option for not writing the client environment variable at all? This is the CONVEX_URL / VITE_CONVEX_URL etc. one.
2. For CONVEX_DEPLOYMENT, it would be nice if CONVEX_DEPLOY_KEY or --env-file also caused this not to be written. It sounds like you want another option, which is if CONVEX_DEPLOYMENT is set (and as long as that's a valid) it won't be written. That part sounds good.