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
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 will then create:
- The
convex/
directory: This is the home for your query and mutation functions. .env.local
withCONVEX_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.
Log out
npx convex logout
Remove the existing Convex credentials from your device, so subsequent commands
like npx convex dev
can use a different Convex account.
Develop
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.
Open the dashboard
npx convex dashboard
Open the Convex 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 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.
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
Import data from a file
npx convex import --table <tableName> <path>
npx convex import <path>.zip
See description and use-cases: snapshot 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: snapshot export.
Display data from tables
npx convex data # lists tables
npx convex data <table>
Display a simple view of the dashboard data page in the command line.
The command supports --limit
and --order
flags to change data displayed. For
more complex filters, use the dashboard data page or write a
query.
The npx convex data <table>
command works with
system tables, such as _storage
, in
addition 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 otherwise manage on the dashboard environment variables settings page.
Deploy
Deploy Convex functions to production
npx convex deploy
The target deployment to push to is determined like this:
- If the
CONVEX_DEPLOY_KEY
environment variable is set (typical in CI), then it is the deployment associated with that key. - If the
CONVEX_DEPLOYMENT
environment variable is set (typical during local development), then the target deployment is the production deployment of the project that the deployment specified byCONVEX_DEPLOYMENT
belongs to. This allows you to deploy to your prod deployment while developing against your dev deployment.
This command will:
- Run a command if specified with
--cmd
. The command will have CONVEX_URL (or similar) environment variable available:You can customize the URL environment variable name withnpx convex deploy --cmd "npm run build"
--cmd-url-env-var-name
:npx convex deploy --cmd 'npm run build' --cmd-url-env-var-name CUSTOM_CONVEX_URL
- Typecheck your Convex functions.
- Regenerate the generated code in the
convex/_generated
directory. - Bundle your Convex functions and their dependencies.
- Push your functions, indexes, and schema to production.
Once this command succeeds the new functions will be available immediately.
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:
-
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-create
option can be used to customize the name associated with the newly created deployment.npx convex deploy --preview-create my-branch-name
-
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
-
Typecheck your Convex functions.
-
Regenerate the generated code in the
convex/_generated
directory. -
Bundle your Convex functions and their dependencies.
-
Run a function specified by
--preview-run
(similar to the--run
option fornpx 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.