feat: warn and add opt-out flag for browse CLI .env auto-loading

[shrey150]

Summary

browse has auto-loaded a .env file from the current directory on startup since it moved into this monorepo, with no way to turn it off. A user reported .env values in one project being silently overridden by a stale shell-level key from another project -- the shell-level BROWSERBASE_API_KEY from an earlier project took precedence over the correct key in a different project's .env, so session replays went to the wrong Browserbase account.

The agreed direction (per internal eng review) is that CLI tools used across many unrelated projects/directories shouldn't auto-load .env at all -- only process.env should matter, and it's on the user to export vars or source .env themselves. Ripping that out in one PR would break the existing install base that relies on the implicit behavior, so this PR is the non-breaking first step:

• Default behavior is unchanged: browse still loads .env by default.
• New BROWSE_LOAD_DOTENV env var makes that behavior explicitly toggleable: 0/false/no (case-insensitive) skips .env loading entirely today; any other explicit value (e.g. 1) keeps loading with no nagging.
• When the toggle is left unset (the implicit default) and loading a .env file actually applies a variable not already in process.env, we print a one-time deprecation warning to stderr naming the variable(s), so people relying on the implicit default get advance notice.

A future PR (not this one) will flip the default of BROWSE_LOAD_DOTENV to off, once the warning has had time to reach users.

This complements #2360, which adds a browse doctor warning when process.env and .env/.env.local values disagree -- a useful on-demand diagnostic, but it doesn't touch the auto-load behavior itself. This PR does not depend on #2360.

E2E Test Matrix

Built the CLI locally (pnpm turbo run build --filter=browse) and ran the built bin/run.js directly in a scratch temp dir containing a .env with a fake BROWSERBASE_API_KEY.

Command / flow	Observed output	Confidence / sufficiency
node bin/run.js doctor --json in scratch dir with .env containing BROWSERBASE_API_KEY=<fake>, BROWSE_LOAD_DOTENV unset	stderr: [browse] Loaded BROWSERBASE_API_KEY from .env. Auto-loading .env is deprecated and will be disabled by default in a future release -- export these variables in your shell instead, or set BROWSE_LOAD_DOTENV=1 to keep this behavior explicitly once that happens. Set BROWSE_LOAD_DOTENV=0 to opt out today. Run \browse doctor` to check for conflicts with your shell environment./ stdoutverdict: "ok"` / exit 0	Proves default (implicit) path still loads .env and now warns exactly once, naming the applied var.
node bin/run.js doctor --remote in same dir with BROWSE_LOAD_DOTENV=0	stdout: [fail] browserbase BROWSERBASE_API_KEY is not set / no stderr / exit 1	Proves opting out today skips .env entirely -- the key never reaches process.env, no warning printed (explicit choice).
node bin/run.js doctor --remote in same dir with BROWSE_LOAD_DOTENV=1	stdout: [ok] browserbase BROWSERBASE_API_KEY is set / no stderr / exit 0	Proves explicit opt-in keeps loading .env with zero nagging.
pnpm exec vitest run tests/cli-cloud-contract.test.ts tests/doctor.test.ts	Test Files 2 passed (2) / Tests 69 passed (69)	Covers the existing .env-loads-config contract (unchanged default) plus: warns when unset+applied, silent when BROWSE_LOAD_DOTENV=1, and fails auth (key never loaded, no warning) for each of 0/false/no/FALSE/NO as BROWSE_LOAD_DOTENV -- added the extra opt-out aliases per cubic review feedback below.
pnpm exec eslint bin/run.js tests/cli-cloud-contract.test.ts + pnpm exec prettier --check bin/run.js README.md tests/cli-cloud-contract.test.ts + pnpm exec tsc --noEmit -p tsconfig.json	All clean, no output/errors	Static checks on touched files; supporting evidence, not a substitute for the live runs above.

Linear

STG-2579 (linked via branch name).

[changeset-bot]

🦋 Changeset detected

Latest commit: c888e25

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

1 issue found across 4 files

Confidence score: 5/5

• packages/cli/tests/cli-cloud-contract.test.ts only validates BROWSE_LOAD_DOTENV="0", so a future change could accidentally break the documented "false"/"no" opt-out behavior without being caught, potentially confusing users who rely on README examples. This PR looks safe to merge, but add explicit tests for "false" and "no" to lock the contract in.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/tests/cli-cloud-contract.test.ts">

<violation number="1" location="packages/cli/tests/cli-cloud-contract.test.ts:737">
P3: The README documents `0`, `false`, and `no` as equivalent opt-out values for `BROWSE_LOAD_DOTENV`, but the tests only cover `"0"`. Consider adding test coverage for `"false"` and `"no"` to ensure the documented behavior is exercised and doesn't regress.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User Shell
    participant CLI as browse CLI
    participant DotEnv as dotenv Module
    participant ProcessEnv as process.env
    participant Stderr as stderr Output
    participant Backend as Backend API

    Note over User,Backend: Browse CLI startup flow with .env auto-loading

    User->>CLI: Run browse command (e.g., browse cloud projects list)
    CLI->>DotEnv: Check for .env in current directory
    
    alt .env file exists
        DotEnv->>DotEnv: Parse .env file
        
        alt BROWSE_LOAD_DOTENV unset (implicit default)
            DotEnv->>ProcessEnv: Load .env variables into process.env
            DotEnv->>DotEnv: Check if any .env vars are NEW (not already in process.env)
            alt New vars applied
                DotEnv-->>Stderr: Print deprecation warning listing variable names
            else All vars already set in process.env
                DotEnv-->>Stderr: No warning (silent load)
            end
        else BROWSE_LOAD_DOTENV = "1" / "true" / explicit value
            DotEnv->>ProcessEnv: Load .env variables into process.env
            DotEnv-->>Stderr: No warning (explicit opt-in)
        else BROWSE_LOAD_DOTENV = "0" / "false" / "no"
            DotEnv->>DotEnv: Skip .env loading entirely
            DotEnv-->>Stderr: No warning (explicit opt-out)
        end
    else No .env file
        DotEnv-->>CLI: No .env to load
    end

    CLI->>ProcessEnv: Read BROWSERBASE_API_KEY
    
    alt Key is set
        CLI->>Backend: API call with API key
        Backend-->>CLI: Response
        CLI-->>User: Success output
    else Key is missing
        CLI-->>User: Error: Missing API key
    end

    Note over DotEnv,Stderr: Future release: default flips to skip .env loading

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>