convex dev command starts a development workflow that watches for file changes, updates generated types, and pushes code to your configured dev deployment.
Usage
Workflow
When you runconvex dev, it:
- Configures a new or existing project (if needed)
- Updates generated types and pushes code to the configured dev deployment
- Runs the provided command (if
--runor--run-shis used) - Watches for file changes and repeats step 2
Options
Show full listing of changes and detailed output.
Check TypeScript files with
tsc --noEmit.Choices: enable, try, disableenable- Always run typechecking, fail if errors foundtry- Run typechecking but don’t fail on errorsdisable- Skip typechecking entirely
Check TypeScript files within component implementations with
tsc --noEmit.Regenerate code in
convex/_generated/.Choices: enable, disableExecute only the first 3 steps, stop on any failure. Useful for CI/CD pipelines.
Execute only the first 3 steps. On failure, watch for local and remote changes and retry steps 2 and 3.
The identifier of a Convex function to run after successful push.Example:
api.init.createData or myDir/myFile:myFunctionConflicts with --run-sh.If
--run is used and the function is in a component, the path to the component tree defined in convex.config.ts.Components are a beta feature. This flag may change in subsequent releases.A shell command to run after successful push.Example:
node myScript.jsIf you just want to run a Convex function, use --run instead.Conflicts with --run.Choose whether to tail Convex function logs in this terminal.Choices:
always, pause-on-deploy, disableIgnore existing configuration and configure new or existing project.Choices:
new, existingCan be used with --team, --project, and --dev-deployment for non-interactive configuration.Examples
Basic development
Start development with default settings:Run a function after each push
Execute a seed function after each successful deployment:Run a shell command
Start your frontend dev server after Convex is ready:One-time push for CI/CD
Push code once without watching (useful in CI pipelines):Disable typechecking
Skip TypeScript checks for faster iteration:Develop against production
Develop live against your production deployment (use with caution):Configuration
Theconvex dev command reads configuration from:
convex.json- Project configuration file- Environment variables -
CONVEX_DEPLOYMENT,CONVEX_URL, etc. .env.local- Local environment variables (overridden by--env-file)
Exit codes
0- Success1- Error occurred-2- Process interrupted (SIGINT)