Skip to main content
The convex deploy command deploys your Convex functions to your production deployment. By default, it deploys to your prod deployment, but it can also create and deploy to preview deployments when using Preview Deploy Keys.

​
Usage

npx convex deploy [options]

​
Options

​
-v, --verbose
boolean
Show full listing of changes and detailed output.
​
--dry-run
boolean
Print out the generated configuration without deploying to your Convex deployment.
​
-y, --yes
boolean
Skip confirmation prompt when running locally.
​
--typecheck
string
default:"try"
Check TypeScript files with tsc --noEmit before deploying.Choices: enable, try, disable
​
--typecheck-components
boolean
default:false
Check TypeScript files within component implementations with tsc --noEmit.
​
--codegen
string
default:"enable"
Regenerate code in convex/_generated/ before pushing.Choices: enable, disable
​
--cmd
string
Command to run as part of deploying your app (e.g., vite build).This command can depend on the environment variables specified in --cmd-url-env-var-name being set.
​
--cmd-url-env-var-name
string
Environment variable name to set Convex deployment URL when using --cmd.Example: VITE_CONVEX_URL
​
--preview-create
string
The name to associate with a newly created preview deployment.Defaults to the current Git branch name in Vercel, Netlify, and GitHub CI.Can only be used with a Preview Deploy Key (set via CONVEX_DEPLOY_KEY).Conflicts with --preview-name.
​
--preview-run
string
Function to run if deploying to a preview deployment.Ignored when deploying to a production deployment.

​
Environment variables

​
CONVEX_DEPLOY_KEY
string
Deploy key for authentication. The type of key determines the deployment target:
  • Production Deploy Key - Deploys to production
  • Preview Deploy Key - Creates or updates a preview deployment
Generate deploy keys in the Convex dashboard under Settings > Deploy Keys.
​
CONVEX_DEPLOYMENT
string
Deployment name to deploy to (alternative to using deploy keys).

​
Examples

​
Deploy to production

Deploy to your production deployment: 
export CONVEX_DEPLOY_KEY=prod_deploy_key_here
npx convex deploy

​
Preview deployment (CI/CD)

Create or update a preview deployment in CI: 
export CONVEX_DEPLOY_KEY=preview_deploy_key_here
npx convex deploy --preview-create "feature-branch"

​
Deploy with build command

Run your frontend build after deploying Convex: 
npx convex deploy --cmd "npm run build" --cmd-url-env-var-name VITE_CONVEX_URL

​
Dry run

Check what would be deployed without actually deploying: 
npx convex deploy --dry-run

​
Deploy and run a function

Deploy to preview and run a seed function: 
export CONVEX_DEPLOY_KEY=preview_deploy_key_here
npx convex deploy --preview-run api.seed.initialize

​
Preview deployments

Preview deployments allow you to create temporary deployments for testing:
  1. Generate a Preview Deploy Key in your Convex dashboard
  2. Set CONVEX_DEPLOY_KEY to your Preview Deploy Key
  3. Run npx convex deploy --preview-create <name>
The CLI automatically detects the branch name from:
  • Vercel (VERCEL_GIT_COMMIT_REF)
  • Netlify (BRANCH)
  • GitHub Actions (GITHUB_HEAD_REF or GITHUB_REF_NAME)

​
Build environment checks

The CLI checks for non-production build environments (Vercel, Netlify, GitHub Actions) when deploying to production and warns if you might be deploying from the wrong environment. Disable this check with: 
npx convex deploy --check-build-environment disable

​
Exit codes

  • 0 - Deployment successful
  • 1 - Deployment failed or was cancelled

Build docs developers (and LLMs) love

Get started for freeTalk to us