support self-host env variables and flags in regular npx convex dev|deploy|run|etc (#34177)

1. check for CONVEX_SELF_HOST_URL and CONVEX_SELF_HOST_ADMIN_KEY env variables in all of the CLI commands, and consider them to be url and admin key if provided
2. avoid checking usage state, which is a big brain api call, if we're doing "urlWithAdminKey"
3. throw error if you've configured self-hosting but you also have cloud-hosting specific variables or flags set -- specifically CONVEX_DEPLOYMENT and `--prod`/`--preview-name`/etc.

this PR doesn't delete the `self-host` subcommand yet, nor does it rename SELF_HOST to SELF_HOSTED which can be in separate PRs.

GitOrigin-RevId: 0804513a2cf504a62b374179bacfca9d6c70a05a

Author: ldanilek

npm-packages/convex/src/cli/configure.ts

@@ -12,6 +12,7 @@ import {
   DeploymentName,
   fetchDeploymentCredentialsProvisioningDevOrProdMaybeThrows,
   createProject,
+  DeploymentSelection,
 } from "./lib/api.js";
 import {
   configFilepath,
@@ -72,6 +73,7 @@ export async function deploymentCredentialsOrConfigure(
   ctx: Context,
   chosenConfiguration: ChosenConfiguration,
   cmdOptions: {
+    deploymentSelection: DeploymentSelection;
     prod: boolean;
     localOptions: {
       ports?: {
@@ -88,21 +90,33 @@ export async function deploymentCredentialsOrConfigure(
     cloud?: boolean | undefined;
     url?: string | undefined;
     adminKey?: string | undefined;
+    envFile?: string | undefined;
   },
   partitionId?: number | undefined,
 ): Promise<
   DeploymentCredentials & {
     deploymentName?: DeploymentName;
   }
 > {
-  if (cmdOptions.url !== undefined && cmdOptions.adminKey !== undefined) {
+  if (cmdOptions.deploymentSelection.kind === "urlWithAdminKey") {
     const credentials = await handleManuallySetUrlAndAdminKey(ctx, {
-      url: cmdOptions.url,
-      adminKey: cmdOptions.adminKey,
+      url: cmdOptions.deploymentSelection.url,
+      adminKey: cmdOptions.deploymentSelection.adminKey,
     });
     return { ...credentials };
   }
 
+  if (
+    cmdOptions.deploymentSelection.kind !== "ownDev" &&
+    cmdOptions.deploymentSelection.kind !== "ownProd"
+  ) {
+    return await ctx.crash({
+      exitCode: 1,
+      errorType: "fatal",
+      printedMessage: `Invalid deployment selection: ${cmdOptions.deploymentSelection.kind}.`,
+    });
+  }
+
   const config = readGlobalConfig(ctx);
   const globallyForceCloud = !!config?.optOutOfLocalDevDeploymentsUntilBetaOver;
   if (globallyForceCloud && cmdOptions.local) {
@@ -129,11 +143,12 @@ export async function deploymentCredentialsOrConfigure(
   // TODO complain about any non-default cmdOptions.localOptions here
   // because we're ignoring them if this isn't a local development.
 
-  const deploymentOptions: DeploymentOptions = cmdOptions.prod
-    ? { kind: "prod" }
-    : devDeployment === "local"
-      ? { kind: "local", ...cmdOptions.localOptions }
-      : { kind: "dev" };
+  const deploymentOptions: DeploymentOptions =
+    cmdOptions.deploymentSelection.kind === "ownProd"
+      ? { kind: "prod" }
+      : devDeployment === "local"
+        ? { kind: "local", ...cmdOptions.localOptions }
+        : { kind: "dev" };
   const {
     deploymentName,
     deploymentUrl: url,

npm-packages/convex/src/cli/convexExport.ts

@@ -23,7 +23,10 @@ export const convexExport = new Command("export")
   .action(async (options) => {
     const ctx = oneoffContext();
 
-    const deploymentSelection = deploymentSelectionFromOptions(options);
+    const deploymentSelection = await deploymentSelectionFromOptions(
+      ctx,
+      options,
+    );
 
     const {
       adminKey,

npm-packages/convex/src/cli/convexImport.ts

@@ -27,7 +27,10 @@ export const convexImport = new Command("import")
 
     await ensureHasConvexDependency(ctx, "import");
 
-    const deploymentSelection = deploymentSelectionFromOptions(options);
+    const deploymentSelection = await deploymentSelectionFromOptions(
+      ctx,
+      options,
+    );
 
     const deploymentNotice = options.prod
       ? ` in your ${chalk.bold("prod")} deployment`

npm-packages/convex/src/cli/dashboard.ts

@@ -24,7 +24,10 @@ export const dashboard = new Command("dashboard")
   .action(async (options) => {
     const ctx = oneoffContext();
 
-    const deploymentSelection = deploymentSelectionFromOptions(options);
+    const deploymentSelection = await deploymentSelectionFromOptions(
+      ctx,
+      options,
+    );
     const { deploymentName } = await fetchDeploymentCredentialsProvisionProd(
       ctx,
       deploymentSelection,

npm-packages/convex/src/cli/data.ts

@@ -22,7 +22,10 @@ export const data = new Command("data")
   .showHelpAfterError()
   .action(async (tableName, options) => {
     const ctx = oneoffContext();
-    const deploymentSelection = deploymentSelectionFromOptions(options);
+    const deploymentSelection = await deploymentSelectionFromOptions(
+      ctx,
+      options,
+    );
 
     const {
       adminKey,

npm-packages/convex/src/cli/deploy.ts

@@ -21,13 +21,15 @@ import {
 import { PushOptions } from "./lib/push.js";
 import {
   CONVEX_DEPLOY_KEY_ENV_VAR_NAME,
+  CONVEX_SELF_HOSTED_URL_VAR_NAME,
   bigBrainAPI,
   getConfiguredDeployment,
   readAdminKeyFromEnvVar,
 } from "./lib/utils/utils.js";
 import { runFunctionAndLog } from "./lib/run.js";
 import { usageStateWarning } from "./lib/usage.js";
 import {
+  CONVEX_DEPLOYMENT_VAR_NAME,
   deploymentTypeFromAdminKey,
   getConfiguredDeploymentFromEnvVar,
   isPreviewDeployKey,
@@ -76,6 +78,14 @@ export const deploy = new Command("deploy")
       .hideHelp()
       .conflicts("preview-create"),
   )
+  .addOption(
+    new Option(
+      "--env-file <envFile>",
+      `Path to a custom file of environment variables, for choosing the \
+deployment, e.g. ${CONVEX_DEPLOYMENT_VAR_NAME} or ${CONVEX_SELF_HOSTED_URL_VAR_NAME}. \
+Same format as .env.local or .env files, and overrides them.`,
+    ),
+  )
   .addOption(new Option("--partition-id <id>").hideHelp())
   .showHelpAfterError()
   .action(async (cmdOptions) => {
@@ -98,12 +108,11 @@ export const deploy = new Command("deploy")
       });
     }
 
-    await usageStateWarning(ctx);
-
     if (
       configuredDeployKey !== null &&
       isPreviewDeployKey(configuredDeployKey)
     ) {
+      await usageStateWarning(ctx);
       if (cmdOptions.previewName !== undefined) {
         await ctx.crash({
           exitCode: 1,
@@ -247,12 +256,16 @@ async function deployToExistingDeployment(
     writePushRequest?: string | undefined;
     liveComponentSources?: boolean | undefined;
     partitionId?: string | undefined;
+    envFile?: string | undefined;
   },
 ) {
-  const deploymentSelection = deploymentSelectionFromOptions({
+  const deploymentSelection = await deploymentSelectionFromOptions(ctx, {
     ...options,
-    prod: true,
+    implicitProd: true,
   });
+  if (deploymentSelection.kind !== "urlWithAdminKey") {
+    await usageStateWarning(ctx);
+  }
   const { name: configuredDeploymentName, type: configuredDeploymentType } =
     getConfiguredDeploymentFromEnvVar();
   const { adminKey, url, deploymentName, deploymentType } =

npm-packages/convex/src/cli/dev.ts

@@ -5,6 +5,9 @@ import { checkAuthorization, performLogin } from "./lib/login.js";
 import { usageStateWarning } from "./lib/usage.js";
 import { normalizeDevOptions } from "./lib/command.js";
 import { devAgainstDeployment } from "./lib/dev.js";
+import { deploymentSelectionFromOptions } from "./lib/api.js";
+import { CONVEX_DEPLOYMENT_VAR_NAME } from "./lib/deployment.js";
+import { CONVEX_SELF_HOSTED_URL_VAR_NAME } from "./lib/utils/utils.js";
 
 export const dev = new Command("dev")
   .summary("Develop against a dev deployment, watching for changes")
@@ -54,6 +57,14 @@ export const dev = new Command("dev")
       .default(false)
       .hideHelp(),
   )
+  .addOption(
+    new Option(
+      "--env-file <envFile>",
+      `Path to a custom file of environment variables, for choosing the \
+deployment, e.g. ${CONVEX_DEPLOYMENT_VAR_NAME} or ${CONVEX_SELF_HOSTED_URL_VAR_NAME}. \
+Same format as .env.local or .env files, and overrides them.`,
+    ),
+  )
   .addOption(new Option("--skip-push").default(false).hideHelp())
   .addOption(new Option("--admin-key <adminKey>").hideHelp())
   .addOption(new Option("--url <url>").hideHelp())
@@ -95,6 +106,20 @@ export const dev = new Command("dev")
 
     const devOptions = await normalizeDevOptions(ctx, cmdOptions);
 
+    const deploymentSelection = await deploymentSelectionFromOptions(
+      ctx,
+      cmdOptions,
+      [
+        ["prod", "--prod"],
+        ["local", "--local"],
+        ["cloud", "--cloud"],
+        ["team", "--team"],
+        ["project", "--project"],
+        ["devDeployment", "--dev-deployment"],
+        ["configure", "--configure"],
+      ],
+    );
+
     if (cmdOptions.configure === undefined) {
       if (cmdOptions.team || cmdOptions.project || cmdOptions.devDeployment)
         return await ctx.crash({
@@ -143,7 +168,7 @@ export const dev = new Command("dev")
       localOptions["forceUpgrade"] = cmdOptions.localForceUpgrade;
     }
 
-    if (!cmdOptions.url || !cmdOptions.adminKey) {
+    if (deploymentSelection.kind !== "urlWithAdminKey") {
       if (!(await checkAuthorization(ctx, false))) {
         await performLogin(ctx, cmdOptions);
       }
@@ -160,11 +185,14 @@ export const dev = new Command("dev")
       {
         ...cmdOptions,
         localOptions,
+        deploymentSelection,
       },
       partitionId,
     );
 
-    await usageStateWarning(ctx);
+    if (deploymentSelection.kind !== "urlWithAdminKey") {
+      await usageStateWarning(ctx);
+    }
 
     if (cmdOptions.skipPush) {
       return;

npm-packages/convex/src/cli/disableLocalDev.ts

@@ -36,6 +36,7 @@ export const disableLocalDeployments = new Command("disable-local-deployments")
     }
 
     await deploymentCredentialsOrConfigure(ctx, null, {
+      deploymentSelection: { kind: "ownDev" },
       prod: false,
       localOptions: {
         forceUpgrade: false,

npm-packages/convex/src/cli/env.ts

@@ -39,7 +39,10 @@ async function selectEnvDeployment(
   ctx: Context,
   options: DeploymentSelectionOptions,
 ) {
-  const deploymentSelection = deploymentSelectionFromOptions(options);
+  const deploymentSelection = await deploymentSelectionFromOptions(
+    ctx,
+    options,
+  );
   const { adminKey, url, deploymentName, deploymentType } =
     await fetchDeploymentCredentialsWithinCurrentProject(
       ctx,

npm-packages/convex/src/cli/functionSpec.ts

@@ -21,7 +21,10 @@ export const functionSpec = new Command("function-spec")
   .showHelpAfterError()
   .action(async (options) => {
     const ctx = oneoffContext();
-    const deploymentSelection = deploymentSelectionFromOptions(options);
+    const deploymentSelection = await deploymentSelectionFromOptions(
+      ctx,
+      options,
+    );
 
     const { adminKey, url: deploymentUrl } =
       await fetchDeploymentCredentialsWithinCurrentProject(