Skip to main content

CLI

The Convex command-line interface (CLI) is your interface for managing Convex projects and Convex functions.

To install the CLI, run:

npm install convex

You can view the full list of commands with:

npx convex

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 will then create:

  1. The convex/ directory: This is the home for your query and mutation functions.
  2. .env.local with CONVEX_DEPLOYMENT variable: This is the main configuration for your Convex project. It is the name of your development deployment.

Recreate project configuration​

Run

npx convex dev

in a project directory without a set CONVEX_DEPLOYMENT to configure a new or existing project.

Write Code​

Run the Convex dev server​

npx convex dev

Watches the local filesystem. When you change a function or the schema, the new versions are pushed to your dev deployment and the generated types in convex/_generated are updated.

Deploy Convex functions to production​

npx convex deploy

This command will:

  1. Typecheck your Convex functions.
  2. Regenerate the generated code in the convex/_generated directory.
  3. Bundle your Convex functions and their dependencies.
  4. Push your functions, indexes, and schema to production.

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

Modify authentication settings​

npx convex auth <subcommand>

Update the authentication settings for your application. The possible subcommands are:

  • add
  • remove
  • list

To learn more about adding authentication to your app, see Authentication.

Misc​

Run Convex functions​

npx convex run <functionName> [args]

Run a public or internal Convex query, mutation, or action after pushing local code.

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 --no-push to run the active version of the code without pushing local changes.

The default is to run functions in your dev deployment. Use --prod to run functions in the production deployment for a project.

Import data from a file into a table​

npx convex import <tableName> <path>

Import a CSV, JSON, or JSONLines file into a Convex table.

  • .csv files must have a header, and each row's entries are interpreted either as a (floating point) number or a string.
  • .json files must be an array of JSON objects.
  • .jsonl files must have a JSON object per line.

Imports into a table with existing data will fail by default, but you can specify --append to append the imported rows to the table or --replace to replace existing data in the table with your import.

The default is to import into your dev deployment. Use --prod to import to your production deployment

Limitations​

Currently Convex only supports imports of up to 8192 rows and 8MiB in size. To work around this, you can split your large import file into smaller files and run npx convex import --append for each one. Feel free to ping us in the community Discord if you would like better support for large imports!

Update generated code​

npx convex codegen

Update the generated code in convex/_generated without pushing. This can be useful for orchestrating build steps in CI.

Open the dashboard​

npx convex dashboard

Open the Convex dashboard.

Open the docs​

npx convex docs

Get back to these docs!

Tail development logs​

npx convex dev --tail-logs

This simultaneously deploys code to the Convex dev server, watching for filesystem changes, and pipes logs generated on the dev server to your console.