Skip to main content

npx convex run

Run a function or evaluate an inline readonly query on your deployment.

  • Run a function with JSON arguments: npx convex run messages:send '{"body": "hello", "author": "me"}'
  • Run a function on prod: npx convex run messages:list --prod
  • Live-update a query's result: npx convex run messages:list --watch
  • Push local code before running: npx convex run messages:send '{}' --push
  • Evaluate an inline readonly query: npx convex run --inline-query 'await ctx.db.query("messages").take(5)'

Arguments are specified as a JSON object. By default, this runs on your dev deployment.

Usage​

npx convex run [options] [functionName] [args]

Arguments​

[functionName]

identifier of the function to run, like listMessages or dir/file:myFunction

[args]

JSON-formatted arguments object to pass to the function.

Options​

-w, --watch

Watch a query, printing its result if the underlying data changes. Given function must be a query.

--inline-query <query>

JavaScript to evaluate as a readonly query. The query is completely sandboxed, so it can only read data and cannot modify the database or access the network.

This is a one-shot query and cannot be combined with --watch. Use --component to target a mounted component.

To format the query:

  • Simple expressions are returned automatically, for example: await ctx.db.query("messages").take(5).
  • For multi-statement queries, use an explicit return, for example: const firstMessage = await ctx.db.query("messages").first(); console.log(firstMessage?._id); return firstMessage;.
  • For full control, pass a module source that exports a default query, for example: export default query({ handler: async (ctx) => { return await ctx.db.query("messages").take(10); } }).
--push

Push code to deployment before running the function.

--identity <identity>

JSON-formatted UserIdentity object, e.g. '{ name: "John", address: "0x123" }'

--typecheck <mode>

Whether to check TypeScript files with tsc --noEmit.

--typecheck-components

Check TypeScript files within component implementations with tsc --noEmit.

--codegen <mode>

Regenerate code in convex/_generated/

--component <path>

Path to the component (e.g. "workflow" or "workflow/workpool")

--prod

Run the function on this project's default production deployment.

--deployment <deployment>

Run the function on a specific deployment. Accepts:

  • a deployment name (e.g. joyful-capybara-123)
  • a deployment reference (e.g. dev/james, staging)
  • dev (for your personal dev deployment)
  • prod (for your project’s default production deployment)
  • local (for your local dev deployment). You can also select deployments in other projects with project-slug:reference or team-slug:project-slug:reference.