Convex operator

Write Convex actions and scheduled work, covering the Node runtime directive, calling external services with timeouts and bounded retries, reading secrets from deployment environment variables, the loss of transactional guarantees across runQuery and runMutation, idempotency for retried work, scheduler runAfter and runAt, cron definitions, HTTP endpoints for inbound webhooks, and keeping actions internal. Use when a function must call an external API, when work must run later or on a schedule, when an inbound webhook must be received, or when an action is partially applying its changes.

Wire authentication into Convex and enforce access inside functions, covering the auth configuration file and identity provider domain and application id, the authenticated client provider, reading identity with getUserIdentity, mapping the provider subject onto a local user row, per-document authorization checks, server-side rendering with a token, and why client-side gating is not access control. Use when functions must know who is calling, when identity is null despite a signed-in user, or when access must be scoped per document.

Answer quick Convex questions with a compact reference for CLI commands, the three function types and when each applies, argument validators, schema and index definitions, database reader and writer methods, query and pagination hooks, scheduling and crons, file storage calls, environment variables, and generated API imports. Use when someone asks which Convex command, function type, or client call to use, or wants a fast lookup rather than a guided workflow.

Deploy Convex and manage its environments, covering the difference between the development watcher and a production deploy, deploy keys for a pipeline, environment variables per deployment, preview deployments for branches, build integration with a frontend deploy, data export and import between deployments, backward-compatible function and schema rollout, and rollback. Use when a change must reach production, when a pipeline must deploy Convex, when environment variables differ between deployments, or when a deploy broke a running client.

Inspect which Convex deployment is active, whether the project is linked and the generated API exists, the deployment URL the application reads, environment variables set on each deployment, the schema and index state, function and cron inventory, and recent logs, without changing anything. Use before a Convex operation, when it is unclear whether a command targets development or production, when generated types are missing, or when the user asks whether Convex is set up.

Store and serve files through Convex storage, covering upload URLs generated in a mutation, direct browser uploads, recording the storage id on a document, serving with getUrl or an HTTP action, content type and size validation, authorizing access per file, deleting a file alongside its referencing row, and finding orphaned files. Use when files must be uploaded or served, when a stored file URL returns nothing, or when file access must be restricted to its owner.

Write and repair Convex queries and mutations, covering argument validators, public versus internal functions, authorization inside the handler, index-backed reads, pagination, transactional guarantees and read and write limits, helper functions shared between handlers, optimistic updates on the client, and errors surfaced to callers. Use when a function must be added or fixed, when a query is slow or hits a read limit, when a mutation must stay atomic, or when a function is callable by clients that should not reach it.

Connect Convex to the systems around it, covering React and Next.js clients with server-side rendering, identity providers through the auth config, external services called from actions, inbound webhooks on HTTP endpoints, mirroring an external system's records into Convex tables, file and email providers, and pipeline test and deploy steps. Use when a frontend must consume Convex reactively, when an identity provider or payment service must be wired in, or when another system's data must be kept in step with Convex.

Discover, compatibility-check, install, update, or explain Convex's first-party agent skills. Use when asked about Convex native skills, get-convex/agent-skills, agent setup, or whether installed Convex skills match the project's current Convex package and runtime.

Define and change Convex tables, covering field validators, optional and union types, typed document references, index design for the queries that exist, search indexes, schema validation against existing documents, migrating data when a field's shape changes, and the difference between a development push and a production deploy. Use when a table must be added or reshaped, when a schema push is rejected, when a query needs an index, or when a field must change type without losing data.

Set up a Convex project from zero, covering package install, project initialization and deployment linking, the development watcher that generates the API, the client provider for a framework, environment variables for local and hosted use, a first schema and function, and separating the development deployment from production. Use when a repository has no Convex directory, when the generated API is missing, when a project must be linked to a deployment, or when the user asks how to get Convex running.

Diagnose Convex failures from reproducible evidence, covering a missing generated API, queries stuck loading, null identity, rejected schema pushes, read and write limit errors from unindexed queries, argument validator failures, actions partially applying changes, missing deployment environment variables after deploy, broken open clients after an incompatible deploy, and development versus production data confusion. Use when a function errors, when a query never resolves, when a deploy broke something, or when it works locally and fails in production.