Convex Plugin

OpenPets plugin for the Convex Management API - provides tools for managing Convex projects, deployments, and custom domains.

Features

This plugin automatically generates tools from the Convex OpenAPI specification:

Core Tools (Always Available)

• convex-test-connection - Test API connection and verify credentials
• convex-get-token-details - Get information about your access token (team ID, type, etc.)

Management Tools (Requires CONVEX_LOAD_OTHER_TOOLS=true)

• Project Management

  • convex-create-project - Create new Convex projects
  • convex-list-projects - List all projects in a team
  • convex-delete-project - Delete a project and all its deployments

• Deployment Management

  • convex-list-deployments - List deployments for a project
  • convex-create-deploy-key - Create deploy keys for CLI access
  • convex-delete-deployment - Delete a specific deployment

• Custom Domain Management

  • convex-list-custom-domains - List custom domains for a deployment
  • convex-create-custom-domain - Add custom domain to deployment
  • convex-delete-custom-domain - Remove custom domain from deployment

Quick Start

1. Installation

# Install the plugin
pets add @openpets/convex

# Or if developing locally
cd pets/convex
bun install

2. Configuration

Create a .env file:

# Required: Get your token from https://docs.convex.dev/management-api
# Team tokens can manage all projects in your team
CONVEX_ACCESS_TOKEN=your_convex_access_token_here

# Optional: Enable all management tools
CONVEX_LOAD_OTHER_TOOLS=true

3. Test Connection

# Test basic connection
opencode run "test convex connection"

# Get token details (shows team ID and token type)
opencode run "get convex token details"

Usage Examples

Basic Operations (Core Tools)

# Test connection and verify token
opencode run "test convex connection"

# Get token information including team ID
opencode run "get convex token details"

Project Management (Requires CONVEX_LOAD_OTHER_TOOLS=true)

# List all projects in your team
opencode run "list my convex projects"

# Create a new project with development deployment
opencode run "create a new convex project called My App with dev deployment"

# List deployments for a specific project
opencode run "list deployments for project 12345"

Custom Domain Management

# List custom domains for a deployment
opencode run "list custom domains for deployment playful-otter-123"

# Add a custom domain
opencode run "create custom domain api.example.com for deployment playful-otter-123"

# Remove a custom domain
opencode run "delete custom domain api.example.com from deployment playful-otter-123"

Authentication

The Convex plugin supports two types of access tokens:

Team Tokens (Recommended)

• Can manage all projects in your team
• Can create new projects
• Get from: Team Settings → API Tokens in Convex Dashboard

Project Tokens

• Limited to a specific project
• Cannot create new projects
• Useful for CI/CD automation

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CONVEX_ACCESS_TOKEN | Yes | Convex access token (team or project token) | | CONVEX_LOAD_OTHER_TOOLS | No | Set to 'true' to enable project/deployment management tools |

Read-Only Mode

Enable read-only mode to prevent accidental modifications:

# Enable read-only for convex plugin
pets read-only convex on

# Only read operations will be available
opencode run "list my convex projects"  # ✅ Works
opencode run "create new project"      # ❌ Blocked

# Disable read-only mode
pets read-only convex off

Development

Local Development

cd pets/convex

# Regenerate OpenAPI tools from latest spec
pets generate-openapi --verbose

# Test locally
opencode run "test convex connection" --print-logs

File Structure

pets/convex/
├── package.json           # Plugin configuration and OpenAPI spec config
├── index.ts              # Main plugin with custom tools
├── openapi-client.ts     # Auto-generated OpenAPI tools
├── opencode.json         # OpenCode configuration
├── .env.example         # Environment variable template
└── README.md            # This file

Updating Tools

When Convex updates their API, regenerate tools:

cd pets/convex
pets generate-openapi

This will:

• Fetch the latest OpenAPI spec from https://api.convex.dev/v1/openapi.json
• Regenerate all tools with latest endpoints
• Preserve custom tools in index.ts

OpenAPI Generation

This plugin uses the official OpenPets OpenAPI generator:

{
  "openapiSpec": {
    "url": "https://api.convex.dev/v1/openapi.json",
    "baseUrl": "https://api.convex.dev/v1",
    "authType": "bearer",
    "authEnvVar": "CONVEX_ACCESS_TOKEN",
    "coreEndpoints": {
      "tags": ["Projects", "Deployments"],
      "paths": ["/token_details"],
      "operationIds": ["get token details"]
    }
  }
}

• Core tools: Always loaded (connection testing, token details)
• LoadEnv tools: Require CONVEX_LOAD_OTHER_TOOLS=true to enable
• Read-only support: Automatically filters write operations when enabled

Error Handling

All tools return structured JSON responses:

{
  "success": true,
  "data": {...},
  "message": "Operation completed successfully"
}

{
  "success": false,
  "error": "HTTP 401: Unauthorized",
  "status": 401
}

Common Use Cases

1. Team Project Management

# List all team projects
opencode run "list my convex projects"

# Create new project for development
opencode run "create a new convex project called dev-service with dev deployment"

# List deployments to get deployment name for CLI usage
opencode run "list deployments for the new project"

2. Deployment Automation

# Create deploy key for CI/CD
opencode run "create deploy key for deployment playful-otter-123 called cicd-key"

# Use deploy key with Convex CLI
convex deploy --key "dev:playful-otter-123|your_generated_key"

3. Custom Domain Management

# Add custom domain for API
opencode run "create custom domain api.example.com for deployment prod-deployment-456"

# List all custom domains
opencode run "list custom domains for deployment prod-deployment-456"

# Remove old domain
opencode run "delete custom domain old-api.example.com from deployment prod-deployment-456"

Security Best Practices

1. Use Team Tokens for project management operations
2. Use Project Tokens for automated deployments (least privilege)
3. Enable Read-Only Mode when just browsing resources
4. Rotate Tokens regularly via Convex dashboard
5. Never Commit .env files with tokens

Troubleshooting

"Not Configured" Error

# Check if token is set
echo $CONVEX_ACCESS_TOKEN

# Test token with curl
curl -H "Authorization: Bearer $CONVEX_ACCESS_TOKEN" https://api.convex.dev/v1/token_details

"Missing Tools" Error

Most tools require an environment variable:

# Enable all tools
export CONVEX_LOAD_OTHER_TOOLS=true
opencode run "list my convex projects"

Permission Errors

• Ensure your token has required permissions
• Team tokens need team admin access
• Project tokens need project admin access

Support

• Convex Management API Documentation
• OpenPets Development Guide
• OpenAPI Generation Guide