Skip to main content
Run a function (query, mutation, or action) on your deployment. This is useful for testing functions, running one-off operations, or watching query results in real-time.

​
Usage

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

​
Arguments

​
functionName
string
required
Identifier of the function to run, like listMessages or dir/file:myFunction.
npx convex run messages:list
​
args
string
JSON-formatted arguments object to pass to the function. Defaults to {}.
npx convex run messages:send '{"text": "Hello", "userId": "123"}'

​
Options

​
--watch
boolean
Watch a query, printing its result if the underlying data changes. The function must be a query.
npx convex run messages:list --watch
​
--push
boolean
Push code to deployment before running the function. Not supported for production deployments.
npx convex run myFunction --push
​
--identity
string
JSON-formatted UserIdentity object to run the function as a specific user.
npx convex run myQuery --identity '{"name": "John", "tokenIdentifier": "user_123"}'
​
--component
string
Path to the component in the component tree defined in convex.config.ts.
npx convex run myFunction --component my/component
​
--prod
boolean
Run the function on this project’s production deployment instead of dev.
npx convex run myQuery --prod
​
--typecheck
string
Whether to check TypeScript files with tsc --noEmit. Options: enable, try, disable. Defaults to try.Only used when --push is specified.
npx convex run myFunction --push --typecheck enable
​
--typecheck-components
boolean
Check TypeScript files within component implementations with tsc --noEmit. Defaults to false.Only used when --push is specified.
npx convex run myFunction --push --typecheck-components
​
--codegen
string
Regenerate code in convex/_generated/. Options: enable, disable. Defaults to enable.Only used when --push is specified.
npx convex run myFunction --push --codegen enable
​
--env-file
string
Path to a custom file of environment variables for choosing the deployment. Same format as .env.local or .env files, and overrides them.
npx convex run myFunction --env-file .env.staging

​
Examples

​
Run a query

Execute a query function and see the result: 
npx convex run messages:list

​
Run a mutation with arguments

Execute a mutation with JSON arguments: 
npx convex run messages:send '{"text": "Hello, world!", "channel": "general"}'

​
Watch a query for changes

Continuously watch a query and see updates when data changes: 
npx convex run messages:list --watch

​
Run with push

Push your latest code changes and then run the function: 
npx convex run myNewFunction --push

​
Run on production

Execute a query on your production deployment: 
npx convex run analytics:getDailyStats --prod

​
Run as a specific user

Execute a function with a user identity: 
npx convex run users:getProfile --identity '{"tokenIdentifier": "user_123"}'

​
Complex arguments

Pass complex nested objects: 
npx convex run createOrder '{
  "items": [{"id": "item1", "quantity": 2}],
  "shipping": {"address": "123 Main St", "city": "NYC"},
  "total": 99.99
}'

​
Common use cases

​
Testing during development

Quickly test a function you’re working on: 
npx convex run myFunction --push

​
One-off data operations

Run a mutation to fix or update data: 
npx convex run admin:migrateUserData '{"batchSize": 100}'

​
Real-time monitoring

Watch query results update live during development: 
npx convex run dashboard:getMetrics --watch

​
Production queries

Inspect production data safely with read-only queries: 
npx convex run reports:getMonthlyRevenue '{"month": "2024-01"}' --prod

​
Notes

  • The --push flag is not supported for production deployments. Use npx convex deploy to push to production.
  • When using --watch, press Ctrl+C to stop watching and exit.
  • Arguments must be valid JSON. Use single quotes around the JSON string in bash/zsh shells.
  • Query functions are read-only and safe to run on production.
  • Be careful when running mutations on production deployments.

Build docs developers (and LLMs) love

Get started for freeTalk to us