Convex CLI expert for serverless backend and real-time database. Use when users need to deploy functions, manage environments, or import/export data.
/plugin marketplace add leobrival/topographic-studio-plugins/plugin install dev@topographic-plugins-officialThis skill inherits all available tools. When active, it can use any tool Claude has access to.
reference/commands-reference.mdreference/common-patterns.mdreference/troubleshooting.mdConvex is a serverless backend platform with a built-in real-time database. This guide provides essential workflows and quick references for common Convex operations.
# Check CLI installation
convex --version
# Authenticate with Convex
convex login
# Initialize new project
convex init
# Start local development
convex dev
# Deploy to production
convex deploy
# View deployment status
convex deployments list
# Login and initialize
convex login
convex init
# Start dev server with hot reload
convex dev
# Dev server runs at http://localhost:3210
# Changes to functions auto-reload
# Dashboard shows data and logs in real-time
# Create function in convex/queries/ or convex/mutations/
# Test function locally
convex run queries/getUser --args '{"id": "123"}'
# Deploy to production
convex deploy --typecheck
# Monitor logs
convex logs --prod --follow
# Set API keys for current environment
convex env set API_KEY sk_test_123
convex env set DATABASE_URL postgres://...
# Set production secrets
convex env set SECRET_KEY value --prod
# List all variables
convex env list
# Export data before major changes
convex export --all --output backup.json
# Import seed data
convex import users seed-users.json
# Batch import multiple tables
convex import --all data/
# Backup production data
convex export --all --prod --output prod-backup.json
# Stream production logs
convex logs --prod --follow
# Filter logs by function
convex logs --function myFunction --level error
# Test function in production
convex run queries/getUser --args '{"id": "123"}' --prod
# View all function executions
convex dashboard --logs
When to use which command:
convex dev for local server with hot reloadconvex run function-name --args '...'convex deploy with --typecheck and --dry-run firstconvex env set/get/list commandsconvex export --all --output backup.jsonconvex import table-name file.jsonconvex logs --follow for real-time monitoring# 1. Start development
convex dev
# 2. Edit functions in convex/queries/, convex/mutations/
# 3. Test locally
convex run queries/myFunction --args '{"key": "value"}'
# 4. Type check and deploy
convex deploy --typecheck
# 5. Monitor
convex logs --prod --follow
# Preview changes
convex deploy --dry-run
# Deploy with message
convex deploy --message "feat: added user authentication"
# Monitor after deploy
convex logs --prod --limit 50
# Development variables
convex env set NODE_ENV development
convex env set LOG_LEVEL debug
# Production variables
convex env set NODE_ENV production --prod
convex env set LOG_LEVEL error --prod
# Verify variables
convex env list
convex env list --prod
# Regular backups
convex export --all --output "backup-$(date +%Y-%m-%d).json"
# Seed data for testing
convex import users test-data/users.json
# Database migrations
convex export --all --output pre-migration.json
# Update schema.ts
convex deploy
# Verify with: convex run queries/checkSchema
Common Issues:
Dev server won't start
convex dev --clear-deployment to reset stateFunction not found error
Environment variables not loading
convex env set KEY value and redeployDeployment fails with type errors
convex deploy --typecheck to check types firstCannot access production data
--prod flag with commandsFor detailed troubleshooting steps, see the Troubleshooting Guide.
Load as needed for detailed information:
Commands Reference - Complete CLI command documentation with all flags and options. Use when you need exact syntax or flag details for any Convex command.
Common Patterns - Real-world patterns and workflows for development, data management, deployment, team collaboration, monitoring, and CI/CD integration. Use for implementing specific workflows or integrations.
Troubleshooting Guide - Detailed error messages, diagnosis steps, and resolution strategies for authentication, development, deployment, functions, data, environment, and configuration issues. Use when encountering errors or unexpected behavior.
When to use each reference:
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.