npm install convex

npx convex

Configure​

Create a new project​

The first time you run

npx convex dev

it will ask you to log in your device and create a new Convex project. It willthen create:

1. Theconvex/ directory: This is the home for your query and mutationfunctions.
2. .env.local withCONVEX_DEPLOYMENT variable: This is the mainconfiguration for your Convex project. It is the name of your developmentdeployment.

Recreate project configuration​

Run

npx convex dev

in a project directory without a setCONVEX_DEPLOYMENT to configure a new orexisting project.

Log out​

npx convex logout

Remove the existing Convex credentials from your device, so subsequent commandslikenpx convex dev can use a different Convex account.

Develop​

Run the Convex dev server​

npx convex dev

Watches the local filesystem. When you change afunction ortheschema, the new versions are pushed to your devdeployment and thegenerated types inconvex/_generated areupdated. By default, logs from your dev deployment are displayed in theterminal.

It's also possible torun a Convex deployment locally fordevelopment.

Open the dashboard​

npx convex dashboard

Open theConvex dashboard.

Open the docs​

npx convex docs

Get back to these docs!

Run Convex functions​

npx convex run <functionName> [args]

Run a public or internal Convex query, mutation, or action on your developmentdeployment.

Arguments are specified as a JSON object.

npx convex run messages:send '{"body": "hello", "author": "me"}'

Add--watch to live update the results of a query. Add--push to push localcode to the deployment before running the function.

Use--prod to run functions in the production deployment for a project.

Tail deployment logs​

You can choose how to pipe logs from your dev deployment to your console:

# Show all logs continuously
npx convex dev --tail-logs always

# Pause logs during deploys to see sync issues (default)
npx convex dev

# Don't display logs while developing
npx convex dev --tail-logs disable

# Tail logs without deploying
npx convex logs

Use--prod withnpx convex logs to tail the prod deployment logs instead.

Import data from a file​

npx convex import --table <tableName> <path>
npx convex import <path>.zip

See description and use-cases:data import.

Export data to a file​

npx convex export --path <directoryPath>
npx convex export --path <filePath>.zip
npx convex export --include-file-storage --path <path>

See description and use-cases:data export.

Display data from tables​

npx convex data  # lists tables
npx convex data <table>

Display a simple view of thedashboard data page in the command line.

The command supports--limit and--order flags to change data displayed. Formore complex filters, use the dashboard data page or write aquery.

Thenpx convex data <table> command works withsystem tables, such as_storage, inaddition to your own tables.

Read and write environment variables​

npx convex env list
npx convex env get <name>
npx convex env set <name> <value>
npx convex env remove <name>

See and update the deployment environment variables which you can otherwisemanage on the dashboardenvironment variables settings page.

Deploy​

Deploy Convex functions to production​

npx convex deploy

The target deployment to push to is determined like this:

1. If theCONVEX_DEPLOY_KEY environment variable is set (typical in CI), thenit is the deployment associated with that key.
2. If theCONVEX_DEPLOYMENT environment variable is set (typical during localdevelopment), then the target deployment is the production deployment of theproject that the deployment specified byCONVEX_DEPLOYMENT belongs to. Thisallows you to deploy to your prod deployment while developing against yourdev deployment.

This command will:

1. Run a command if specified with--cmd. The command will have CONVEX_URL (orsimilar) environment variable available:

   npx convex deploy --cmd "npm run build"
   

   You can customize the URL environment variable name with--cmd-url-env-var-name:

   npx convex deploy --cmd 'npm run build' --cmd-url-env-var-name CUSTOM_CONVEX_URL
   

2. Typecheck your Convex functions.
3. Regenerate thegenerated code in theconvex/_generateddirectory.
4. Bundle your Convex functions and their dependencies.
5. Push your functions,indexes,andschema to production.

Once this command succeeds the new functions will be available immediately.

Deploy Convex functions to apreview deployment​

npx convex deploy

When run with theCONVEX_DEPLOY_KEY environment variable containing aPreview Deploy Key,this command will:

1. Create a new Convex deployment.npx convex deploy will infer the Git branchname for Vercel, Netlify, GitHub, and GitLab environments, or the--preview-create option can be used to customize the name associated withthe newly created deployment.

   npx convex deploy --preview-create my-branch-name
   

2. Run a command if specified with--cmd. The command will have CONVEX_URL (orsimilar) environment variable available:

   npx convex deploy --cmd "npm run build"
   

   You can customize the URL environment variable name with--cmd-url-env-var-name:

   npx convex deploy --cmd 'npm run build' --cmd-url-env-var-name CUSTOM_CONVEX_URL
   

3. Typecheck your Convex functions.

4. Regenerate thegenerated code in theconvex/_generateddirectory.

5. Bundle your Convex functions and their dependencies.

6. Push your functions,indexes,andschema to the deployment.

7. Run a function specified by--preview-run (similar to the--run optionfornpx convex dev).

   npx convex deploy --preview-run myFunction
   

See theVercel orNetlify hosting guide forsetting up frontend and backend previews together.

Update generated code​

npx convex codegen

Thegenerated code in theconvex/_generated directoryincludes types required for a TypeScript typecheck. This code is generatedwhenever necessary while runningnpx convex dev and this code should becommitted to the repo (your code won't typecheck without it!).

In the rare cases it's useful to regenerate code (e.g. in CI to ensure that thecorrect code was checked it) you can use this command.

Generating code can require communicating with a convex deployment in order toevaluate configuration files in the Convex JavaScript runtime. This doesn'tmodify the code running on the deployment.