[CATALYST-1744] - add --env-path flag

[jamesqquick]

What/Why?

This allows the user to specify a environment variable file to load variables from

Testing

Create a .env.test file with credentials. Start by running catalyst project list with no variables and show that the command fails. Then, run catalyst project list --env-path .env.test with valid variables and show that it works.

To test the priority of variables loaded from the file taking precedence over existing process.env variables, set an access token in environment variable with an invalid take. CATALYST_ACCESS_TOKEN=dummy_token. Run the catalyst project list command again, and prove that it still works.

Migration

If you want to load environment variables from a file, update your commands to include --env-path flag.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Feb 19, 2026 5:40pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: e706439

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

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

Click here to learn what changesets are, and how to add one.

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

[matthewvolk]

Just a big question about the loadEnvFileFromArgv function, and whether console.warn is the behavior we want.

[matthewvolk]

🍹 Not a common edge case, but know that if a user does something like --env-file --other-option (basically forgets to add a value for --env-file), this function silently does nothing. Might be an opportunity to add something like:

if (!value || value.startsWith('-')) {
  throw new Error('--env-file requires a path argument');
}

[jamesqquick]

It looks like commander handles that by default interestingly. Do you think it's still worth adding a check?

[matthewvolk]

🍹 The throw new Error() from loadEnvFileFromArgv will surface as an unhandled exception with a full stack trace — not great UX for a CLI. Wrap it in a try/catch for a clean exit

try {
  loadEnvFileFromArgv(process.argv);
} catch (e) {
  consola.error(e instanceof Error ? e.message : e);
  process.exit(1);
}

[matthewvolk]

Ok, figured out the issue with --env-file:

Node.js itself added support for the same exact flag starting in Node 20.6.0:
https://nodejs.org/api/environment_variables.html#env-files

Node is intercepting --env-file .en and trying to load it before your script even executes.

When you pass a valid file, Node loads it successfully, then your command's own --env-file handling in loadEnvFileFromArgv processes it a second time.

TL;DR, I think the best option is to rename the flag, e.g., --env-path (is that confusing?). I don't think there's a clean way to disable Node.js's built-in flag parsing, and honestly I don't think we'd want to.

[chanceaclark]

LGTM with the approach.

[jorgemoya]

Missing some tests just to make sure this is working as expected.