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. Run a command if specified with --cmd. The command will have CONVEX_URL (or similar) 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 the generated code in the convex/_generated directory.
  4. Bundle your Convex functions and their dependencies.
  5. 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 on your development deployment.

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 local code to the deployment before running the function.

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!

Deploy Convex functions to a preview deployment​

npx convex deploy

When run with the CONVEX_DEPLOY_KEY environment variable containing a Preview Deploy Key, this command will:

  1. Create a deployment with the specified name. npx convex deploy will infer the Git branch name for Vercel, Netlify, GitHub, and GitLab environments, but the --preview-name option can be used to customize the name associated with the newly created deployment.

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

  2. Run a command if specified with --cmd. The command will have CONVEX_URL (or similar) 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 the generated code in the convex/_generated directory.

  5. Bundle your Convex functions and their dependencies.

  6. Push your functions, indexes, and schema to the deployment.

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

    npx convex deploy --preview-run myFunction

See the Vercel or Netlify hosting guide for setting up frontend and backend previews together.

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 deployment logs​

npx convex logs

This pipes logs from your dev deployment to your console. This can be followed with --prod to tail the prod deployment logs instead.

You can also simultaneously deploy code to the Convex dev deployment, watching for filesystem changes, and pipe logs generated on your dev deployment to your console:

npx convex dev --tail-logs