Convex

Convex Operations

Backend skill wrapping npx convex CLI. Routes to workflows for specific operations.

Project Detection

Run first to verify you're in a Convex project:

[ -d "convex" ] && echo "Convex project detected" || echo "ERROR: No convex/ directory found"

If no convex/ directory: Run npx convex init to initialize.

Quick Actions

Available Scripts

Execute directly - they handle errors and edge cases:

Common Commands Reference

# Development
npx convex dev                    # Start dev server with hot reload

# Deployment
npx convex deploy                 # Deploy to production

# Functions
npx convex run api:functionName   # Run a function
npx convex run api:func --arg '{"key":"value"}'  # With arguments

# Data
npx convex export --path ./backup.zip   # Export all data
npx convex import --path ./backup.zip   # Import data

# Environment
npx convex env list               # List env vars
npx convex env set KEY=value      # Set env var
npx convex env get KEY            # Get env var

# Other
npx convex dashboard              # Open dashboard in browser
npx convex codegen                # Regenerate types
npx convex logs --name prod       # View production logs

Safety Rules

1. Always check project - Verify convex/ directory exists before running commands
2. Deploy key for CI - Production deploys need CONVEX_DEPLOY_KEY (see deploy workflow)
3. Backup before import - Always export before importing data
4. Review schema changes - Schema migrations can be destructive

🚨 CRITICAL: Auto-Clean Before Any Convex Command

ALWAYS prefix Convex commands with this cleanup:

rm -f convex/*.js 2>/dev/null; npx convex dev

The "Two output files" Error

If you see:

✘ [ERROR] Two output files share the same path but have different contents: out/auth.js

Cause: Orphan .js files in convex/ folder (from git worktrees, crashes, or manual operations).

Fix: rm -f convex/*.js then retry.

Prevention: Always use the cleanup prefix. Only .ts files belong in convex/.

See workflows/troubleshooting.md for details.