convex 1.40.0 → 1.42.0

package/src/cli/deploymentToken.test.ts

@@ -187,20 +187,23 @@ afterEach(() => {
 });
 
 describe("deployment token create", () => {
-  test("crashes when not authed with a personal access token", async () => {
-    setAuthKind("deploymentKey");
-    mockSelectedDeployment("joyful-capybara-123", "dev");
-
-    await expect(
-      deploymentTokenCreate.parseAsync(["my-token"], { from: "user" }),
-    ).rejects.toThrow();
-    expect(process.stderr.write).toHaveBeenCalledWith(
-      expect.stringContaining(
-        "requires being logged in with a personal access token",
-      ),
-    );
-    expect(mockPlatformPost).not.toHaveBeenCalled();
-  });
+  test.each(["deploymentKey", "projectKey", "previewDeployKey"] as const)(
+    "crashes when authed with a %s instead of a personal access token",
+    async (kind) => {
+      setAuthKind(kind);
+      mockSelectedDeployment("joyful-capybara-123", "dev");
+
+      await expect(
+        deploymentTokenCreate.parseAsync(["my-token"], { from: "user" }),
+      ).rejects.toThrow();
+      expect(process.stderr.write).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "requires being logged in with a personal access token",
+        ),
+      );
+      expect(mockPlatformPost).not.toHaveBeenCalled();
+    },
+  );
 
   test("crashes when no auth is configured at all", async () => {
     setNoAuth();
@@ -311,15 +314,23 @@ describe("deployment token create", () => {
 });
 
 describe("deployment token delete", () => {
-  test("crashes when not authed with a personal access token", async () => {
-    setAuthKind("deploymentKey");
-    mockSelectedDeployment("joyful-capybara-123", "dev");
-
-    await expect(
-      deploymentTokenDelete.parseAsync(["my-token"], { from: "user" }),
-    ).rejects.toThrow();
-    expect(mockPlatformPost).not.toHaveBeenCalled();
-  });
+  test.each(["deploymentKey", "projectKey", "previewDeployKey"] as const)(
+    "crashes when authed with a %s instead of a personal access token",
+    async (kind) => {
+      setAuthKind(kind);
+      mockSelectedDeployment("joyful-capybara-123", "dev");
+
+      await expect(
+        deploymentTokenDelete.parseAsync(["my-token"], { from: "user" }),
+      ).rejects.toThrow();
+      expect(process.stderr.write).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "requires being logged in with a personal access token",
+        ),
+      );
+      expect(mockPlatformPost).not.toHaveBeenCalled();
+    },
+  );
 
   test("sends the friendly name as-is when no `|` is present", async () => {
     setAuthKind("accessToken");

package/src/cli/deploymentTokenCreate.ts

@@ -1,13 +1,14 @@
 import { Command } from "@commander-js/extra-typings";
-import { chalkStderr } from "chalk";
 import { oneoffContext } from "../bundler/context.js";
 import { logFinishedStep, logOutput, showSpinner } from "../bundler/log.js";
 import { loadSelectedDeploymentCredentials } from "./lib/api.js";
 import { actionDescription } from "./lib/command.js";
-import { getDeploymentSelection } from "./lib/deploymentSelection.js";
+import {
+  ensureLoggedInWithAccessToken,
+  getDeploymentSelection,
+} from "./lib/deploymentSelection.js";
 import { changedEnvVarFile } from "./lib/envvars.js";
 import {
-  CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME,
   CONVEX_DEPLOY_KEY_ENV_VAR_NAME,
   ENV_VAR_FILE_PATH,
   typedPlatformClient,
@@ -19,10 +20,10 @@ export const deploymentTokenCreate = new Command("create")
     [
       `Creates a deploy key that, when set as \`${CONVEX_DEPLOY_KEY_ENV_VAR_NAME}\`, scopes all commands to the target deployment.`,
       "",
-      "- Print a new deploy key to stdout: `npx convex deployment token create my-token`",
-      `- Save a new deploy key in \`${ENV_VAR_FILE_PATH}\`: \`npx convex deployment token create my-token --save-env\``,
-      "- Save a new deploy key in a custom env file: `npx convex deployment token create ci-token --save-env .env.production`",
-      "- Create a key for the project's prod: `npx convex deployment token create ci-token --deployment prod`",
+      "• Print a new deploy key to stdout: `npx convex deployment token create my-token`",
+      `• Save a new deploy key in \`${ENV_VAR_FILE_PATH}\`: \`npx convex deployment token create my-token --save-env\``,
+      "• Save a new deploy key in a custom env file: `npx convex deployment token create ci-token --save-env .env.production`",
+      "• Create a key for the project's prod: `npx convex deployment token create ci-token --deployment prod`",
     ].join("\n"),
   )
   .argument("<name>", "Name for the new deploy key")
@@ -36,20 +37,7 @@ export const deploymentTokenCreate = new Command("create")
   .action(async (name, options) => {
     const ctx = await oneoffContext(options);
 
-    const auth = ctx.bigBrainAuth();
-    if (auth === null || auth.kind !== "accessToken") {
-      return await ctx.crash({
-        exitCode: 1,
-        errorType: "fatal",
-        printedMessage: `Creating a deploy key currently requires being logged in with a personal access token. ${
-          process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME]
-            ? `Unset ${CONVEX_DEPLOY_KEY_ENV_VAR_NAME}`
-            : process.env[CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME]
-              ? `Unset ${CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME}`
-              : `Run ${chalkStderr.bold("npx convex login")}`
-        } and try again.`,
-      });
-    }
+    await ensureLoggedInWithAccessToken(ctx, "Creating a deploy key");
 
     const deploymentSelection = await getDeploymentSelection(ctx, options);
     const deployment = await loadSelectedDeploymentCredentials(

package/src/cli/deploymentTokenDelete.ts

@@ -4,12 +4,11 @@ import { oneoffContext } from "../bundler/context.js";
 import { logFinishedStep, showSpinner } from "../bundler/log.js";
 import { loadSelectedDeploymentCredentials } from "./lib/api.js";
 import { actionDescription } from "./lib/command.js";
-import { getDeploymentSelection } from "./lib/deploymentSelection.js";
 import {
-  CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME,
-  CONVEX_DEPLOY_KEY_ENV_VAR_NAME,
-  typedPlatformClient,
-} from "./lib/utils/utils.js";
+  ensureLoggedInWithAccessToken,
+  getDeploymentSelection,
+} from "./lib/deploymentSelection.js";
+import { typedPlatformClient } from "./lib/utils/utils.js";
 
 export const deploymentTokenDelete = new Command("delete")
   .summary("Delete an access token")
@@ -19,9 +18,9 @@ export const deploymentTokenDelete = new Command("delete")
       "",
       "The positional `<nameOrToken>` can be the unique name of the deploy key (as passed to `token create`) or the deploy key value itself. The target deployment defaults to the currently-selected one; pass `--deployment` to target a different deployment.",
       "",
-      "- Delete by name: `npx convex deployment token delete my-token`",
-      "- Delete by value: `npx convex deployment token delete 'dev:happy-animal-123|ey...'`",
-      "- Target prod: `npx convex deployment token delete ci-token --deployment prod`",
+      "• Delete by name: `npx convex deployment token delete my-token`",
+      "• Delete by value: `npx convex deployment token delete 'dev:happy-animal-123|ey...'`",
+      "• Target prod: `npx convex deployment token delete ci-token --deployment prod`",
     ].join("\n"),
   )
   .argument(
@@ -34,21 +33,7 @@ export const deploymentTokenDelete = new Command("delete")
   .action(async (nameOrToken, options) => {
     const ctx = await oneoffContext(options);
 
-    const auth = ctx.bigBrainAuth();
-    if (auth === null || auth.kind !== "accessToken") {
-      return await ctx.crash({
-        exitCode: 1,
-        errorType: "fatal",
-        printedMessage: `Deleting a deploy key requires being logged in with a personal access token. ${
-          auth === null
-            ? "Run "
-            : process.env[CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME] &&
-                !process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME]
-              ? `Unset ${CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME} and run `
-              : `Unset ${CONVEX_DEPLOY_KEY_ENV_VAR_NAME} and run `
-        }${chalkStderr.bold("npx convex login")} and try again.`,
-      });
-    }
+    await ensureLoggedInWithAccessToken(ctx, "Deleting a deploy key");
 
     const deploymentSelection = await getDeploymentSelection(ctx, options);
     const deployment = await loadSelectedDeploymentCredentials(

package/src/cli/dev.ts

@@ -66,7 +66,7 @@ export const dev = new Command("dev")
   .addOption(
     new Option(
       "--start <command>",
-      "Start a long-running command alongside `convex dev`, like a frontend " +
+      "Start a long-running command alongside `npx convex dev`, like a frontend " +
         "dev server. The command inherits stdin/stdout so you can interact " +
         "with it directly. Example: npx convex dev --start 'vite --open'",
     ).conflicts(["--run", "--run-sh"]),
@@ -93,9 +93,9 @@ export const dev = new Command("dev")
       "--tail-logs [mode]",
       [
         "Choose whether to tail Convex function logs in this terminal: ",
-        "- `always` shows logs continuously",
-        "- `pause-on-deploy` (the default) pauses logs during deploys so you can spot sync issues",
-        "- `disable` hides logs while developing.",
+        "• `always` shows logs continuously",
+        "• `pause-on-deploy` (the default) pauses logs during deploys so you can spot sync issues",
+        "• `disable` hides logs while developing.",
       ].join("\n"),
     )
       .choices(["always", "pause-on-deploy", "disable"] as const)
@@ -280,6 +280,7 @@ Same format as .env.local or .env files, and overrides them.`,
                         credentials.deploymentFields.deploymentType,
                     }
                   : {}),
+                backendVersion: localOptions.backendVersion,
               },
               devOptions,
             ),

package/src/cli/env.ts

@@ -32,16 +32,16 @@ const envSetCmd = new Command("set")
     [
       "Set environment variables on your deployment.",
       "",
-      "- `npx convex env set NAME 'value'`",
-      "- `npx convex env set NAME # omit a value to set one interactively`",
-      "- `npx convex env set NAME --from-file value.txt`",
-      "- `npx convex env set --from-file .env.defaults`",
+      "• `npx convex env set NAME 'value'`",
+      "• `npx convex env set NAME # omit a value to set one interactively`",
+      "• `npx convex env set NAME --from-file value.txt`",
+      "• `npx convex env set --from-file .env.defaults`",
       "",
       "When setting multiple values, it will refuse all changes if any variables are already set to different values by default. Pass --force to overwrite the provided values.",
       "",
       "To keep secrets out of your shell history, omit the value to pipe it in via stdin, for instance:",
-      "- `pbpaste | npx convex env set API_KEY` (macOS)",
-      "- `Get-Clipboard | npx convex env set API_KEY` (Windows PowerShell)",
+      "• `pbpaste | npx convex env set API_KEY` (macOS)",
+      "• `Get-Clipboard | npx convex env set API_KEY` (Windows PowerShell)",
       "",
       "To update many variables at once, save them with `npx convex env list > .env.convex`, edit the file, then reapply the changes with `npx convex env set --force < .env.convex`.",
     ].join("\n"),
@@ -164,18 +164,25 @@ const envRemoveCmd = new Command("remove")
   });
 
 const envListCmd = new Command("list")
-  .summary("List all variables")
+  .summary("List all environment variables and their values")
   .description(
     [
-      "- List all variables: `npx convex env list`",
-      "- Save all variables to a file: `npx convex env list > .env.convex`",
-      "- Append to a file: `npx convex env list >> .env.convex`",
+      "• List all variables and their values: `npx convex env list`",
+      "• List only variable names (no values): `npx convex env list --names-only`",
+      "• Save all variables to a file: `npx convex env list > .env.convex`",
+      "• Append to a file: `npx convex env list >> .env.convex`",
     ].join("\n"),
   )
+  .option(
+    "--names-only",
+    "List only the names of environment variables, without their values",
+  )
   .configureHelp({ showGlobalOptions: true })
   .allowExcessArguments(false)
-  .action(async (_options, cmd) => {
-    const options = cmd.optsWithGlobals();
+  .action(async (cmdOptions, cmd) => {
+    // Note: We use `as` here because optsWithGlobals() type inference doesn't
+    // include global options from the parent command (added via addDeploymentSelectionOptions)
+    const options = cmd.optsWithGlobals() as DeploymentSelectionOptions;
     const { ctx, deployment } = await selectEnvDeployment(options);
     await ensureHasConvexDependency(ctx, "env list");
     await withRunningBackend({
@@ -183,7 +190,9 @@ const envListCmd = new Command("list")
       deployment,
       action: async () => {
         const backend = deploymentEnvBackend(ctx, deployment);
-        await envList(ctx, backend);
+        await envList(ctx, backend, {
+          namesOnly: cmdOptions.namesOnly ?? false,
+        });
       },
     });
   });
@@ -194,12 +203,13 @@ export const env = new Command("env")
     [
       "Set and view environment variables on your deployment",
       "",
-      "- Set a variable: `npx convex env set NAME 'value'`",
-      "- Set interactively: `npx convex env set NAME`",
-      "- Set multiple from file: `npx convex env set --from-file .env`",
-      "- Unset a variable: `npx convex env remove NAME`",
-      "- List all variables: `npx convex env list`",
-      "- Print a variable's value: `npx convex env get NAME`",
+      "• Set a variable: `npx convex env set NAME 'value'`",
+      "• Set interactively: `npx convex env set NAME`",
+      "• Set multiple from file: `npx convex env set --from-file .env`",
+      "• Unset a variable: `npx convex env remove NAME`",
+      "• List all variables and their values: `npx convex env list`",
+      "• List only variable names (no values): `npx convex env list --names-only`",
+      "• Print a variable's value: `npx convex env get NAME`",
       "",
       "By default, this sets and views variables on your dev deployment.",
       "",

package/src/cli/envDefault.ts

@@ -52,10 +52,10 @@ const envDefaultSet = addEnvDefaultOptions(
       [
         "Set default environment variables for your project's deployment type.",
         "",
-        "- `npx convex env default set NAME 'value'`",
-        "- `npx convex env default set NAME # omit a value to set one interactively`",
-        "- `npx convex env default set NAME --from-file value.txt`",
-        "- `npx convex env default set --from-file .env.defaults`",
+        "• `npx convex env default set NAME 'value'`",
+        "• `npx convex env default set NAME # omit a value to set one interactively`",
+        "• `npx convex env default set NAME --from-file value.txt`",
+        "• `npx convex env default set --from-file .env.defaults`",
         "",
         "When setting multiple values, it will refuse all changes if any variables are already set to different values by default. Pass --force to overwrite the provided values.",
         "",
@@ -122,7 +122,7 @@ const envDefaultRemove = addEnvDefaultOptions(
       [
         "Unset a default variable.",
         "",
-        "- `npx convex env default remove NAME`",
+        "• `npx convex env default remove NAME`",
         "",
         "If the variable doesn't exist, the command doesn't do anything and succeeds.",
         "",
@@ -141,24 +141,29 @@ const envDefaultRemove = addEnvDefaultOptions(
 
 const envDefaultList = addEnvDefaultOptions(
   new Command("list")
-    .summary("List all default variables")
+    .summary("List all default environment variables and their values")
     .description(
       [
-        "List all default variables.",
-        "",
-        "- `npx convex env default list`",
+        "• List all default variables and their values: `npx convex env default list`",
+        "• List only default variable names (no values): `npx convex env default list --names-only`",
         "",
         "The deployment type is determined by the current deployment (local maps to dev), or by --type if provided.",
       ].join("\n"),
     )
+    .option(
+      "--names-only",
+      "List only the names of environment variables, without their values",
+    )
     .configureHelp({ showGlobalOptions: true })
     .allowExcessArguments(false),
-).action(async (_options, cmd) => {
+).action(async (cmdOptions, cmd) => {
   const options = cmd.optsWithGlobals() as DeploymentSelectionOptions &
     EnvDefaultExtraOptions;
   const { ctx, backend } = await resolveEnvDefaultBackend(options);
   await ensureHasConvexDependency(ctx, "env default list");
-  await envList(ctx, backend);
+  await envList(ctx, backend, {
+    namesOnly: cmdOptions.namesOnly ?? false,
+  });
 });
 
 export const envDefault = new Command("default")
@@ -169,10 +174,11 @@ export const envDefault = new Command("default")
       "",
       "The default environment variables read and written to by this command are the ones for the deployment type of the current deployment (i.e. dev in most cases), unless --type is provided.",
       "",
-      "- Set a default variable: `npx convex env default set NAME 'value'`",
-      "- Unset a default variable: `npx convex env default remove NAME`",
-      "- List all default variables: `npx convex env default list`",
-      "- Print a default variable's value: `npx convex env default get NAME`",
+      "• Set a default variable: `npx convex env default set NAME 'value'`",
+      "• Unset a default variable: `npx convex env default remove NAME`",
+      "• List all default variables and their values: `npx convex env default list`",
+      "• List only default variable names (no values): `npx convex env default list --names-only`",
+      "• Print a default variable's value: `npx convex env default get NAME`",
     ].join("\n"),
   )
   .addCommand(envDefaultSet)

package/src/cli/insights.ts

@@ -92,15 +92,16 @@ export const insights = new Command("insights")
       "Show health insights for a Convex deployment over the last 72 hours.",
       "Displays OCC conflicts and resource limit issues that may indicate performance problems.",
       "",
-      "- Show insights: `npx convex insights`",
-      "- Include recent events for each insight: `npx convex insights --details`",
-      "- Check the production deployment: `npx convex insights --prod`",
+      "• Show insights: `npx convex insights`",
+      "• Include recent events for each insight: `npx convex insights --details`",
+      "• Check the production deployment: `npx convex insights --prod`",
       "",
       "This command is only available for Convex cloud deployments when logged in as a user.",
     ].join("\n"),
   )
   .allowExcessArguments(false)
   .option("--details", "Show recent events for each insight", false)
+  .option("--json", "Output insights as JSON", false)
   .addDeploymentSelectionOptions(actionDescription("Show insights for"))
   .showHelpAfterError()
   .action(async (cmdOptions) => {
@@ -145,6 +146,17 @@ export const insights = new Command("insights")
       "?view=insights",
     );
 
+    if (cmdOptions.json) {
+      logOutput(
+        JSON.stringify(
+          { deploymentName, dashboardUrl, insights: insightsList },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
     if (insightsList.length === 0) {
       logOutput(
         chalk.green(

package/src/cli/lib/aiFiles/integration.test.ts

@@ -151,6 +151,7 @@ describe("ai-files integration with default convex/ directory", () => {
         "add",
         "get-convex/agent-skills",
         "--yes",
+        "--copy",
         "--agent",
         "claude-code",
         "--agent",
@@ -173,6 +174,7 @@ describe("ai-files integration with default convex/ directory", () => {
         "add",
         "get-convex/agent-skills",
         "--yes",
+        "--copy",
         "--agent",
         "cursor",
         "--agent",

package/src/cli/lib/aiFiles/skills.ts

@@ -23,11 +23,11 @@ function configuredSkillAgents(
 }
 
 /**
- * Runs `npx skills add get-convex/agent-skills --yes` in the given directory.
+ * Runs `npx skills add get-convex/agent-skills --yes --copy` in the given directory.
  * Returns true on success, false if the process fails or cannot be started.
  */
 function runSkillsAdd(cwd: string, agents: string[]): Promise<boolean> {
-  const args = ["add", "get-convex/agent-skills", "--yes"];
+  const args = ["add", "get-convex/agent-skills", "--yes", "--copy"];
   for (const agent of agents) {
     args.push("--agent", agent);
   }
@@ -135,7 +135,7 @@ export async function installSkills({
   if (!skillsOk) {
     logMessage(
       chalkStderr.yellow(
-        "Could not install agent skills. You can retry manually with: npx skills add get-convex/agent-skills",
+        "Could not install agent skills. You can retry manually with: npx skills add get-convex/agent-skills --copy",
       ),
     );
     return;

package/src/cli/lib/command.ts

@@ -495,8 +495,8 @@ Command.prototype.addImportOptions = function () {
       new Option(
         "--replace-all",
         "Replace all existing data in the deployment with the imported tables,\n" +
-          "  deleting tables that don't appear in the import file or the schema,\n" +
-          "  and clearing tables that appear in the schema but not in the import file",
+          "deleting tables that don't appear in the import file or the schema,\n" +
+          "and clearing tables that appear in the schema but not in the import file",
       )
         .conflicts("--append")
         .conflicts("--replace"),

package/src/cli/lib/deployment.ts

@@ -255,10 +255,6 @@ export async function getTeamAndProjectFromPreviewAdminKey(
   return { teamSlug, projectSlug };
 }
 
-export type OnDeploymentActivityFunc = (
-  isOffline: boolean,
-  wasOffline: boolean,
-) => Promise<void>;
 export type CleanupDeploymentFunc = () => Promise<void>;
 export type DeploymentDetails = {
   deploymentName: string;
@@ -266,5 +262,4 @@ export type DeploymentDetails = {
   adminKey: string;
   reference: string | null;
   isDefault: boolean;
-  onActivity: OnDeploymentActivityFunc | null;
 };

package/src/cli/lib/deploymentSelection.ts

@@ -35,6 +35,7 @@ import { getBuildEnvironment } from "./envvars.js";
 import { readGlobalConfig } from "./utils/globalConfig.js";
 import {
   CONVEX_DEPLOYMENT_ENV_VAR_NAME,
+  CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME,
   CONVEX_DEPLOY_KEY_ENV_VAR_NAME,
   CONVEX_SELF_HOSTED_ADMIN_KEY_VAR_NAME,
   CONVEX_SELF_HOSTED_URL_VAR_NAME,
@@ -217,6 +218,72 @@ function getBigBrainAuth(
   return null;
 }
 
+// These guards mirror the management API's auth rules client-side so we can
+// fail with a clear message instead of an opaque 401; the server stays
+// authoritative. Creating a deployment also allows project keys, while the
+// deploy-key commands stay personal-access-token only.
+
+/** Crashes unless logged in with a personal access token (not a deploy key). */
+export async function ensureLoggedInWithAccessToken(
+  ctx: Context,
+  action: string,
+): Promise<void> {
+  const auth = ctx.bigBrainAuth();
+  if (auth !== null && auth.kind === "accessToken") {
+    return;
+  }
+  // Name whichever deploy-key env var is in effect (CONVEX_DEPLOY_KEY wins).
+  const prefix =
+    auth === null
+      ? "Run "
+      : process.env[CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME] &&
+          !process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME]
+        ? `Unset ${CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME} and run `
+        : `Unset ${CONVEX_DEPLOY_KEY_ENV_VAR_NAME} and run `;
+  return await ctx.crash({
+    exitCode: 1,
+    errorType: "fatal",
+    printedMessage: `${action} requires being logged in with a personal access token. ${prefix}${chalkStderr.bold(
+      "npx convex login",
+    )} and try again.`,
+  });
+}
+
+/**
+ * Crashes unless the auth can create a deployment: personal access tokens and
+ * project keys are accepted, deploy keys are not.
+ */
+export async function ensureAuthCanCreateDeployment(
+  ctx: Context,
+): Promise<void> {
+  const auth = ctx.bigBrainAuth();
+  if (
+    auth !== null &&
+    (auth.kind === "accessToken" || auth.kind === "projectKey")
+  ) {
+    return;
+  }
+  if (auth === null) {
+    return await ctx.crash({
+      exitCode: 1,
+      errorType: "fatal",
+      printedMessage: `Creating a deployment requires logging in. Run ${chalkStderr.bold(
+        "npx convex login",
+      )} and try again.`,
+    });
+  }
+  const envVar = process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME]
+    ? CONVEX_DEPLOY_KEY_ENV_VAR_NAME
+    : CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME;
+  return await ctx.crash({
+    exitCode: 1,
+    errorType: "fatal",
+    printedMessage: `Creating a deployment isn't supported with a deploy key (${envVar}). Run ${chalkStderr.bold(
+      "npx convex login",
+    )} (or use a project key) and try again.`,
+  });
+}
+
 // ----------------------------------------------------------------------------
 // Deployment Selection
 // ----------------------------------------------------------------------------

package/src/cli/lib/dev.ts

@@ -30,6 +30,9 @@ import {
   syncAuthKitConfigAfterPush,
   ensureAuthKitProvisionedBeforeBuild,
 } from "./workos/workos.js";
+import { handleDashboard } from "./localDeployment/dashboard.js";
+import { loadDeploymentConfig } from "./localDeployment/filePaths.js";
+import { LocalDeploymentError } from "./localDeployment/errors.js";
 
 export async function devAgainstDeployment(
   ctx: OneoffCtx,
@@ -38,6 +41,7 @@ export async function devAgainstDeployment(
     adminKey: string;
     deploymentName: string | null;
     deploymentType?: DeploymentType;
+    backendVersion?: string | undefined;
   },
   devOptions: {
     verbose: boolean;
@@ -82,6 +86,41 @@ export async function devAgainstDeployment(
     }
   }
 
+  // Anonymous mode starts a local dashboard server alongside long-running `npx convex dev` commands.
+  if (
+    !devOptions.once &&
+    !devOptions.untilSuccess &&
+    credentials.deploymentType === "anonymous" &&
+    credentials.deploymentName !== null
+  ) {
+    const deploymentConfig = loadDeploymentConfig(
+      ctx,
+      "anonymous",
+      credentials.deploymentName,
+    );
+    if (deploymentConfig === null) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: `Could not find local deployment config. This is a bug in Convex.`,
+        errForSentry: new LocalDeploymentError(
+          `Could not find local deployment config to start the anonymous dashboard.`,
+        ),
+      });
+    }
+    await handleDashboard(
+      ctx,
+      {
+        name: credentials.deploymentName,
+        cloudPort: deploymentConfig.ports.cloud,
+        adminKey: deploymentConfig.adminKey,
+      },
+      {
+        backendVersion: credentials.backendVersion,
+      },
+    );
+  }
+
   const promises = [];
   if (devOptions.tailLogs !== "disable") {
     promises.push(