Core commands: npx convex dev, npx convex deploy, npx convex codegen, npx convex run (use --prod for prod).
Agent Mode: You SHOULD use CONVEX_AGENT_MODE=anonymous npx convex dev --once when iterating as an AI agent to safely generate codegen artifacts.
Deploy target resolution: CONVEX_DEPLOY_KEY overrides, else uses production of CONVEX_DEPLOYMENT project.
Build step: npx convex deploy --cmd "npm run build" and --cmd-url-env-var-name if needed.
Deploy keys: production, preview, dev, admin (You MUST NOT commit/log).
Hosting flows:
- Vercel/Netlify build command SHOULD use npx convex deploy --cmd 'npm run build'.
- You MUST set CONVEX_DEPLOY_KEY per environment (Preview vs Production).
- Preview seeding via --preview-run 'functionName'.
- Custom hosting: deploy backend, host frontend elsewhere; custom domains require overriding CONVEX_CLOUD_URL and redeploying; optional CONVEX_SITE_URL.

You MUST use exact CLI commands and flags from docs.
You MUST state target deployment resolution (deploy key vs CONVEX_DEPLOYMENT).
You MUST call out deploy-side effects: schema validation, index backfill, codegen, bundling.
You SHOULD always mention .convex.site vs .convex.cloud URL usage where relevant.

Each project has one production deployment and one cloud dev deployment per team member.
Preview deployments are per-branch and are auto-cleaned after a time window.
Local deployments are dev-only and run as subprocesses of npx convex dev.

npx convex dev:
- Watches files, pushes changes to dev deployment.
- Regenerates convex/_generated/*.
- You SHOULD use --tail-logs to control log output.
Local dev:
- npx convex dev --local --once for local backend.
- Note: No public URL; HTTP requests need a proxy (e.g., ngrok).
- Node actions require Node 18 locally.

npx convex deploy:
- Typechecks functions.
- Regenerates codegen.
- Bundles and pushes functions, schema, and indexes.
Deploy target resolution:
- If CONVEX_DEPLOY_KEY is set, deploys to that key's target.
- Else uses the production deployment of CONVEX_DEPLOYMENT's project.
Optional build command:
- npx convex deploy --cmd "npm run build"
- Use --cmd-url-env-var-name to customize env var name.

You MUST set per-deployment via dashboard or npx convex env.
Same key MAY require values in both dev and prod.
System vars:
- CONVEX_CLOUD_URL for client RPCs.
- CONVEX_SITE_URL for HTTP actions.
You MUST NOT branch exports on process.env at runtime; functions set at deploy time.

Schema MUST match existing data; deploy blocks on validation failures.
Safe schema changes:
- Add tables.
- Add optional fields, backfill, then make required.
- Widen via v.union, backfill, then narrow.
Functions MUST remain backward compatible while old clients are running.
Scheduled functions MUST accept previously scheduled args.

New indexes backfill during deploy; CAN slow production push.
You SHOULD use staged indexes (including search/vector) for large tables.
Removing indexes deletes them on deploy; You MUST ensure no code paths depend on them.

convex-deploy