convex 1.36.0 → 1.37.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.36.0",
+  "version": "1.37.0",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
@@ -178,7 +178,7 @@
   "peerDependencies": {
     "@auth0/auth0-react": "^2.0.1",
     "@clerk/clerk-react": "^4.12.8 || ^5.0.0",
-    "@clerk/react": "^6.0.0",
+    "@clerk/react": "^6.4.3",
     "react": "^18.0.0 || ^19.0.0-0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -203,14 +203,14 @@
     "@auth0/auth0-react": "2.15.1",
     "@babel/parser": "^7.27.1",
     "@babel/types": "^7.27.1",
-    "@clerk/react": "^6.0.0",
+    "@clerk/react": "^6.4.3",
     "@commander-js/extra-typings": "^14.0.0",
     "@convex-dev/platform": "0.1.8",
     "@eslint/compat": "~2.0.0",
     "@eslint/eslintrc": "^3",
     "@eslint/js": "~9.39.0",
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "@octokit/openapi-types": "~25.1.0",
+    "@octokit/openapi-types": "~27.0.0",
     "@sentry/node": "^7.23.0",
     "@sentry/tracing": "^7.23.0",
     "@swc/core": "1.15.8",

package/src/cli/codegen_templates/agentsmd.ts

@@ -5,9 +5,13 @@ export function convexAiMarkdownBody(convexDir: string): string {
   const normalizedConvexDir = convexDir.replaceAll("\\", "/");
   return `This project uses [Convex](https://convex.dev) as its backend.
 
-When working on Convex code, **always read \`${normalizedConvexDir}/_generated/ai/guidelines.md\` first** for important guidelines on how to correctly use Convex APIs and patterns. The file contains rules that override what you may have learned about Convex from training data.
+When working on Convex code, **always read
+\`${normalizedConvexDir}/_generated/ai/guidelines.md\` first** for important guidelines on
+how to correctly use Convex APIs and patterns. The file contains rules that
+override what you may have learned about Convex from training data.
 
-Convex agent skills for common tasks can be installed by running \`npx convex ai-files install\`.`;
+Convex agent skills for common tasks can be installed by running
+\`npx convex ai-files install\`.`;
 }
 
 /**
@@ -17,6 +21,8 @@ Convex agent skills for common tasks can be installed by running \`npx convex ai
  */
 export function agentsMdConvexSection(convexDir: string): string {
   return `${AGENTS_MD_START_MARKER}
+
 ${convexAiMarkdownBody(convexDir)}
+
 ${AGENTS_MD_END_MARKER}`;
 }

package/src/cli/codegen_templates/claudemd.ts

@@ -12,6 +12,8 @@ export const CLAUDE_MD_END_MARKER = "<!-- convex-ai-end -->";
  */
 export function claudeMdConvexSection(convexDir: string): string {
   return `${CLAUDE_MD_START_MARKER}
+
 ${convexAiMarkdownBody(convexDir)}
+
 ${CLAUDE_MD_END_MARKER}`;
 }

package/src/cli/configure.ts

@@ -671,15 +671,6 @@ async function selectExistingProject(
 
   logFinishedStep(`Reinitialized project ${chalkStderr.bold(projectSlug)}`);
 
-  const { configPath, projectConfig } = await readProjectConfig(ctx);
-  const folder = functionsDir(configPath, projectConfig);
-  await attemptSetupAiFiles({
-    ctx,
-    aiFilesConfig: projectConfig.aiFiles,
-    convexDir: path.resolve(folder),
-    projectDir: path.resolve(path.dirname(configPath)),
-  });
-
   return { teamSlug, projectSlug, devDeployment };
 }
 

package/src/cli/deployment.ts

@@ -1,9 +1,11 @@
 import { Command } from "@commander-js/extra-typings";
 import { deploymentSelect } from "./deploymentSelect.js";
 import { deploymentCreate } from "./deploymentCreate.js";
+import { deploymentToken } from "./deploymentToken.js";
 
 export const deployment = new Command("deployment")
   .summary("Manage deployments")
   .description("Manage deployments in your project.")
   .addCommand(deploymentSelect)
-  .addCommand(deploymentCreate);
+  .addCommand(deploymentCreate)
+  .addCommand(deploymentToken);

package/src/cli/deploymentToken.test.ts

@@ -0,0 +1,372 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import path from "path";
+import { nodeFs } from "../bundler/fs.js";
+import { deploymentTokenCreate } from "./deploymentTokenCreate.js";
+import { deploymentTokenDelete } from "./deploymentTokenDelete.js";
+import { typedPlatformClient } from "./lib/utils/utils.js";
+import {
+  getDeploymentSelection,
+  initializeBigBrainAuth,
+} from "./lib/deploymentSelection.js";
+import { loadSelectedDeploymentCredentials } from "./lib/api.js";
+import type { Context } from "../bundler/context.js";
+
+vi.mock("@sentry/node", () => ({
+  captureException: vi.fn(),
+  close: vi.fn(),
+}));
+
+vi.mock("../bundler/fs.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../bundler/fs.js")>();
+  return {
+    ...actual,
+    nodeFs: {
+      ...actual.nodeFs,
+      exists: vi.fn(),
+      readUtf8File: vi.fn(),
+      writeUtf8File: vi.fn(),
+      mkdir: vi.fn(),
+    },
+  };
+});
+
+const mockPlatformPost = vi.fn();
+
+vi.mock("./lib/utils/utils.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./lib/utils/utils.js")>();
+  return {
+    ...actual,
+    typedPlatformClient: vi.fn(() => ({ POST: mockPlatformPost })),
+  };
+});
+
+vi.mock("./lib/deploymentSelection.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("./lib/deploymentSelection.js")>();
+  return {
+    ...actual,
+    initializeBigBrainAuth: vi.fn(),
+    getDeploymentSelection: vi.fn(),
+  };
+});
+
+vi.mock("./lib/api.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./lib/api.js")>();
+  return {
+    ...actual,
+    loadSelectedDeploymentCredentials: vi.fn(),
+  };
+});
+
+// Default in-memory FS used when not overridden by a specific test.
+let testFiles: Map<string, string>;
+let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+
+function setAuthKind(
+  kind: "accessToken" | "deploymentKey" | "projectKey" | "previewDeployKey",
+) {
+  vi.mocked(initializeBigBrainAuth).mockImplementation(async (ctx) => {
+    const fakeAuth =
+      kind === "accessToken"
+        ? {
+            kind: "accessToken" as const,
+            accessToken: "test-token",
+            header: "Bearer test-token",
+          }
+        : kind === "deploymentKey"
+          ? {
+              kind: "deploymentKey" as const,
+              deploymentKey: "dev:foo|secret",
+              header: "Bearer dev:foo|secret",
+            }
+          : kind === "projectKey"
+            ? {
+                kind: "projectKey" as const,
+                projectKey: "project:foo|secret",
+                header: "Bearer project:foo|secret",
+              }
+            : {
+                kind: "previewDeployKey" as const,
+                previewDeployKey: "preview:t:p|secret",
+                header: "Bearer preview:t:p|secret",
+              };
+    (ctx as Context)._updateBigBrainAuth(fakeAuth);
+  });
+}
+
+function setNoAuth() {
+  vi.mocked(initializeBigBrainAuth).mockImplementation(async (ctx) => {
+    (ctx as Context)._updateBigBrainAuth(null);
+  });
+}
+
+function mockSelectedDeployment(
+  deploymentName: string,
+  deploymentType: "dev" | "prod" | "preview" | "custom" | "local" | "anonymous",
+) {
+  vi.mocked(getDeploymentSelection).mockResolvedValue({
+    kind: "existingDeployment",
+    deploymentToActOn: {
+      url: `https://${deploymentName}.convex.cloud`,
+      adminKey: "admin-key",
+      source: "deployKey",
+      deploymentFields: {
+        deploymentName,
+        deploymentType,
+        teamSlug: "my-team",
+        projectSlug: "my-project",
+      },
+    },
+  });
+  vi.mocked(loadSelectedDeploymentCredentials).mockResolvedValue({
+    url: `https://${deploymentName}.convex.cloud`,
+    adminKey: "admin-key",
+    deploymentFields: {
+      deploymentName,
+      deploymentType,
+      teamSlug: "my-team",
+      projectSlug: "my-project",
+    },
+  });
+}
+
+beforeEach(() => {
+  vi.resetAllMocks();
+
+  // Set up an in-memory FS that the env-file write/read paths can use.
+  testFiles = new Map();
+  vi.mocked(nodeFs.exists).mockImplementation((p: string) =>
+    testFiles.has(path.resolve(p)),
+  );
+  vi.mocked(nodeFs.readUtf8File).mockImplementation((p: string) => {
+    const content = testFiles.get(path.resolve(p));
+    if (content === undefined) {
+      const err: any = new Error(
+        `ENOENT: no such file or directory, open '${p}'`,
+      );
+      err.code = "ENOENT";
+      throw err;
+    }
+    return content;
+  });
+  vi.mocked(nodeFs.writeUtf8File).mockImplementation(
+    (p: string, content: string) => {
+      testFiles.set(path.resolve(p), content);
+    },
+  );
+
+  vi.mocked(typedPlatformClient).mockReturnValue({
+    POST: mockPlatformPost,
+  } as any);
+  mockPlatformPost.mockReset();
+
+  vi.spyOn(process, "exit").mockImplementation((() => {
+    throw new Error("process.exit called");
+  }) as any);
+  vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+  // logOutput uses console.log, so spy on it (not stdout.write).
+  consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+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("crashes when no auth is configured at all", async () => {
+    setNoAuth();
+    mockSelectedDeployment("joyful-capybara-123", "dev");
+
+    await expect(
+      deploymentTokenCreate.parseAsync(["my-token"], { from: "user" }),
+    ).rejects.toThrow();
+    expect(mockPlatformPost).not.toHaveBeenCalled();
+  });
+
+  test("rejects local deployments client-side", async () => {
+    setAuthKind("accessToken");
+    mockSelectedDeployment("local-deployment", "local");
+
+    await expect(
+      deploymentTokenCreate.parseAsync(["my-token"], { from: "user" }),
+    ).rejects.toThrow();
+    expect(process.stderr.write).toHaveBeenCalledWith(
+      expect.stringContaining("Cannot create a deploy key for a local"),
+    );
+    expect(mockPlatformPost).not.toHaveBeenCalled();
+  });
+
+  test("prints the new deploy key to stdout when --save-env is omitted", async () => {
+    setAuthKind("accessToken");
+    mockSelectedDeployment("joyful-capybara-123", "dev");
+    mockPlatformPost.mockResolvedValue({
+      data: { deployKey: "dev:joyful-capybara-123|new-token" },
+    });
+
+    await deploymentTokenCreate.parseAsync(["my-token"], { from: "user" });
+
+    expect(mockPlatformPost).toHaveBeenCalledWith(
+      "/deployments/{deployment_name}/create_deploy_key",
+      {
+        params: { path: { deployment_name: "joyful-capybara-123" } },
+        body: { name: "my-token" },
+      },
+    );
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      "dev:joyful-capybara-123|new-token",
+    );
+    // .env.local should not have been written.
+    expect(testFiles.has(path.resolve(".env.local"))).toBe(false);
+  });
+
+  test("--save-env writes the key to .env.local by default", async () => {
+    setAuthKind("accessToken");
+    mockSelectedDeployment("joyful-capybara-123", "dev");
+    mockPlatformPost.mockResolvedValue({
+      data: { deployKey: "dev:joyful-capybara-123|new-token" },
+    });
+
+    await deploymentTokenCreate.parseAsync(["my-token", "--save-env"], {
+      from: "user",
+    });
+
+    const written = testFiles.get(path.resolve(".env.local"));
+    expect(written).toContain(
+      "CONVEX_DEPLOY_KEY=dev:joyful-capybara-123|new-token",
+    );
+    // The raw deploy key shouldn't have been printed to stdout.
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+  });
+
+  test("--save-env <path> writes to a custom env file", async () => {
+    setAuthKind("accessToken");
+    mockSelectedDeployment("joyful-capybara-123", "dev");
+    mockPlatformPost.mockResolvedValue({
+      data: { deployKey: "dev:joyful-capybara-123|new-token" },
+    });
+
+    await deploymentTokenCreate.parseAsync(
+      ["ci-token", "--save-env", ".env.production"],
+      { from: "user" },
+    );
+
+    expect(testFiles.has(path.resolve(".env.local"))).toBe(false);
+    const written = testFiles.get(path.resolve(".env.production"));
+    expect(written).toContain(
+      "CONVEX_DEPLOY_KEY=dev:joyful-capybara-123|new-token",
+    );
+  });
+
+  test("--save-env replaces an existing CONVEX_DEPLOY_KEY in the file", async () => {
+    setAuthKind("accessToken");
+    mockSelectedDeployment("joyful-capybara-123", "dev");
+    mockPlatformPost.mockResolvedValue({
+      data: { deployKey: "dev:joyful-capybara-123|new-token" },
+    });
+    testFiles.set(
+      path.resolve(".env.local"),
+      "FOO=bar\nCONVEX_DEPLOY_KEY=dev:joyful-capybara-123|old-token\n",
+    );
+
+    await deploymentTokenCreate.parseAsync(["my-token", "--save-env"], {
+      from: "user",
+    });
+
+    const written = testFiles.get(path.resolve(".env.local"));
+    expect(written).toContain("FOO=bar");
+    expect(written).toContain(
+      "CONVEX_DEPLOY_KEY=dev:joyful-capybara-123|new-token",
+    );
+    expect(written).not.toContain("old-token");
+  });
+});
+
+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("sends the friendly name as-is when no `|` is present", async () => {
+    setAuthKind("accessToken");
+    mockSelectedDeployment("joyful-capybara-123", "dev");
+    mockPlatformPost.mockResolvedValue({ data: undefined });
+
+    await deploymentTokenDelete.parseAsync(["my-token"], { from: "user" });
+
+    expect(mockPlatformPost).toHaveBeenCalledWith(
+      "/deployments/{deployment_name}/delete_deploy_key",
+      {
+        params: { path: { deployment_name: "joyful-capybara-123" } },
+        body: { id: "my-token" },
+      },
+    );
+  });
+
+  test("strips the deploy-key prefix before sending to the server", async () => {
+    setAuthKind("accessToken");
+    mockSelectedDeployment("joyful-capybara-123", "dev");
+    mockPlatformPost.mockResolvedValue({ data: undefined });
+
+    await deploymentTokenDelete.parseAsync(
+      ["dev:joyful-capybara-123|the-secret-token"],
+      { from: "user" },
+    );
+
+    expect(mockPlatformPost).toHaveBeenCalledWith(
+      "/deployments/{deployment_name}/delete_deploy_key",
+      {
+        params: { path: { deployment_name: "joyful-capybara-123" } },
+        body: { id: "the-secret-token" },
+      },
+    );
+  });
+
+  test("warns and crashes when the value looks like an unquoted partial deploy key", async () => {
+    setAuthKind("accessToken");
+    mockSelectedDeployment("joyful-capybara-123", "dev");
+
+    await expect(
+      deploymentTokenDelete.parseAsync(["dev:joyful-capybara-123"], {
+        from: "user",
+      }),
+    ).rejects.toThrow();
+    expect(process.stderr.write).toHaveBeenCalledWith(
+      expect.stringContaining("looks like a partial deploy key"),
+    );
+    expect(mockPlatformPost).not.toHaveBeenCalled();
+  });
+
+  test("rejects local deployments client-side", async () => {
+    setAuthKind("accessToken");
+    mockSelectedDeployment("local-deployment", "local");
+
+    await expect(
+      deploymentTokenDelete.parseAsync(["my-token"], { from: "user" }),
+    ).rejects.toThrow();
+    expect(process.stderr.write).toHaveBeenCalledWith(
+      expect.stringContaining("Cannot delete a deploy key for a local"),
+    );
+    expect(mockPlatformPost).not.toHaveBeenCalled();
+  });
+});

package/src/cli/deploymentToken.ts

@@ -0,0 +1,11 @@
+import { Command } from "@commander-js/extra-typings";
+import { deploymentTokenCreate } from "./deploymentTokenCreate.js";
+import { deploymentTokenDelete } from "./deploymentTokenDelete.js";
+
+export const deploymentToken = new Command("token")
+  .summary("Manage access tokens")
+  .description(
+    "Create and delete access tokens. Currently supports deploy keys.",
+  )
+  .addCommand(deploymentTokenCreate)
+  .addCommand(deploymentTokenDelete);

package/src/cli/deploymentTokenCreate.ts

@@ -0,0 +1,113 @@
+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 { changedEnvVarFile } from "./lib/envvars.js";
+import {
+  CONVEX_DEPLOY_KEY_ENV_VAR_NAME,
+  ENV_VAR_FILE_PATH,
+  typedPlatformClient,
+} from "./lib/utils/utils.js";
+
+export const deploymentTokenCreate = new Command("create")
+  .summary("Create an access token")
+  .description(
+    `Creates a deploy key that, when set as ${chalkStderr.bold(CONVEX_DEPLOY_KEY_ENV_VAR_NAME)}, scopes all commands to the target deployment. Defaults to the current deployment if '--deployment' isn't passed\n\n` +
+      "  Print a new deploy key to stdout:           `npx convex deployment token create my-token`\n" +
+      `  Save a new deploy key in ${ENV_VAR_FILE_PATH}:        \`npx convex deployment token create my-token --save-env\`\n` +
+      "  Save a new deploy key in a custom env file: `npx convex deployment token create ci-token --save-env .env.production`\n" +
+      "  Create a key for the project's prod:        `npx convex deployment token create ci-token --deployment prod`\n",
+  )
+  .argument("<name>", "Name for the new deploy key")
+  .allowExcessArguments(false)
+  .option(
+    "--save-env [path]",
+    `Save the new key as ${CONVEX_DEPLOY_KEY_ENV_VAR_NAME} in an env file instead of printing it. Defaults to ${ENV_VAR_FILE_PATH}.`,
+  )
+  .addDeploymentSelectionOptions(actionDescription("Create a deploy key for"))
+  .showHelpAfterError()
+  .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}`
+            : `Run ${chalkStderr.bold("npx convex login")}`
+        } and try again.`,
+      });
+    }
+
+    const deploymentSelection = await getDeploymentSelection(ctx, options);
+    const deployment = await loadSelectedDeploymentCredentials(
+      ctx,
+      deploymentSelection,
+      { ensureLocalRunning: false },
+    );
+
+    if (deployment.deploymentFields === null) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage:
+          "Cannot create a deploy key for a self-hosted deployment.",
+      });
+    }
+
+    const { deploymentName, deploymentType } = deployment.deploymentFields;
+    if (deploymentType === "local" || deploymentType === "anonymous") {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: `Cannot create a deploy key for a ${deploymentType} deployment.`,
+      });
+    }
+
+    showSpinner(`Creating deploy key for ${deploymentName}...`);
+    const response = await typedPlatformClient(ctx).POST(
+      "/deployments/{deployment_name}/create_deploy_key",
+      {
+        params: { path: { deployment_name: deploymentName } },
+        body: { name },
+      },
+    );
+    const deployKey = response.data!.deployKey;
+
+    if (options.saveEnv === undefined) {
+      logFinishedStep(`Created deploy key "${name}" for ${deploymentName}.`);
+      logOutput(deployKey);
+      return;
+    }
+
+    const envFile =
+      typeof options.saveEnv === "string" ? options.saveEnv : ENV_VAR_FILE_PATH;
+    const existingFileContent = ctx.fs.exists(envFile)
+      ? ctx.fs.readUtf8File(envFile)
+      : null;
+    const updatedContent = changedEnvVarFile({
+      existingFileContent,
+      envVarName: CONVEX_DEPLOY_KEY_ENV_VAR_NAME,
+      envVarValue: deployKey,
+      commentAfterValue: null,
+      commentOnPreviousLine: null,
+    });
+
+    if (updatedContent === null) {
+      logFinishedStep(
+        `Deploy key for ${deploymentName} already present in ${envFile}; no changes made.`,
+      );
+      return;
+    }
+
+    ctx.fs.writeUtf8File(envFile, updatedContent);
+    logFinishedStep(
+      `Saved deploy key "${name}" for ${deploymentName} as ${CONVEX_DEPLOY_KEY_ENV_VAR_NAME} in ${envFile}.`,
+    );
+  });

package/src/cli/deploymentTokenDelete.ts

@@ -0,0 +1,91 @@
+import { Command } from "@commander-js/extra-typings";
+import { chalkStderr } from "chalk";
+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_DEPLOY_KEY_ENV_VAR_NAME,
+  typedPlatformClient,
+} from "./lib/utils/utils.js";
+
+export const deploymentTokenDelete = new Command("delete")
+  .summary("Delete an access token")
+  .description(
+    "Delete an access token. Currently only deploy keys (deployment-scoped access tokens) are supported.\n\n" +
+      "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.\n\n" +
+      "  Delete by name:  `npx convex deployment token delete my-token`\n" +
+      "  Delete by value: `npx convex deployment token delete 'dev:happy-animal-123|ey...'`\n" +
+      "  Target prod:     `npx convex deployment token delete ci-token --deployment prod`",
+  )
+  .argument(
+    "<nameOrToken>",
+    "The unique name of the deploy key, or the deploy key value itself.",
+  )
+  .allowExcessArguments(false)
+  .addDeploymentSelectionOptions(actionDescription("Delete a deploy key for"))
+  .showHelpAfterError()
+  .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 " : `Unset ${CONVEX_DEPLOY_KEY_ENV_VAR_NAME} and run `}${chalkStderr.bold("npx convex login")} and try again.`,
+      });
+    }
+
+    const deploymentSelection = await getDeploymentSelection(ctx, options);
+    const deployment = await loadSelectedDeploymentCredentials(
+      ctx,
+      deploymentSelection,
+      { ensureLocalRunning: false },
+    );
+
+    if (deployment.deploymentFields === null) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage:
+          "Cannot delete a deploy key for a self-hosted deployment.",
+      });
+    }
+
+    const { deploymentName, deploymentType } = deployment.deploymentFields;
+    if (deploymentType === "local" || deploymentType === "anonymous") {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: `Cannot delete a deploy key for a ${deploymentType} deployment.`,
+      });
+    }
+
+    // A full deploy key has the form `<type>:<deployment-name>|<token>`. If we
+    // see the prefix without the `|`, the user almost certainly forgot to
+    // quote: the shell ate `|` and everything after.
+    if (/^(dev|prod|preview|local):[^|]*$/.test(nameOrToken)) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: `"${nameOrToken}" looks like a partial deploy key — your shell likely consumed the \`|\` and everything after it. Wrap the value in single quotes (e.g. ${chalkStderr.bold(`npx convex deployment token delete '${nameOrToken}|...'`)}) and try again.`,
+      });
+    }
+    // The server matches against just the token portion, so strip the prefix
+    // when present so users can paste the value of CONVEX_DEPLOY_KEY directly.
+    const pipeIdx = nameOrToken.indexOf("|");
+    const id = pipeIdx >= 0 ? nameOrToken.slice(pipeIdx + 1) : nameOrToken;
+
+    showSpinner(`Deleting deploy key for ${deploymentName}...`);
+    await typedPlatformClient(ctx).POST(
+      "/deployments/{deployment_name}/delete_deploy_key",
+      {
+        params: { path: { deployment_name: deploymentName } },
+        body: { id },
+      },
+    );
+
+    logFinishedStep(`Deleted deploy key for ${deploymentName}.`);
+  });