convex deploy

Deploy to your production deployment

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