Agent Skills: Convex Manager

Convex Manager

Available Operations

List Projects

List all Convex projects for your team:

./scripts/list_projects.py

Output format:

{
  "projects": [
    {
      "id": 123,
      "name": "my-project",
      "slug": "my-project",
      "deployments": [...]
    }
  ]
}

The script automatically:

• Reads CONVEX_TOKEN from the .env file
• Calls the token details endpoint to get your team ID
• Lists all projects for your team

Create Project

Create a new Convex project:

./scripts/create_project.py <project_name> [deployment_type]

Arguments:

• project_name: Name of the project to create (required)
• deployment_type: Either dev or prod (optional, default: dev)

Example:

./scripts/create_project.py my-new-app dev

Output format:

{
  "projectId": 456,
  "deploymentName": "my-new-app",
  "deploymentUrl": "https://example-slug-789.convex.cloud"
}

Delete Project

Delete a project and all its deployments:

./scripts/delete_project.py <project_id>

Arguments:

• project_id: Numeric ID of the project to delete (required)

Example:

./scripts/delete_project.py 456

WARNING: This permanently deletes the project and ALL its deployments. Use list_projects.py to find project IDs before deleting.

Output format:

{
  "status": "success",
  "message": "Project 456 deleted"
}

Create Production Deployment

Add a production deployment to an existing project:

./scripts/create_production_deployment.py <team_slug> <project_id>

Arguments:

• team_slug: Team slug (required, e.g., 'my-team')
• project_id: Numeric ID of the project (required)

Example:

./scripts/create_production_deployment.py my-team 1209929

Output format:

{
  "projectName": "my-app",
  "projectSlug": "my-app",
  "deploymentName": "happy-whale-456",
  "deploymentUrl": "https://happy-whale-456.convex.cloud",
  "status": "success"
}

Note: This creates a production deployment for a project that currently only has a dev deployment. If the project already has a production deployment, the script will error.

List Deployments

List all deployments for a project:

./scripts/list_deployments.py <project_id>

Arguments:

• project_id: Numeric ID of the project (required)

Example:

./scripts/list_deployments.py 1209929

Output format:

[
  {
    "name": "playful-otter-123",
    "deploymentType": "dev",
    "createTime": 1760880185840,
    "projectId": 1209929
  },
  {
    "name": "happy-whale-456",
    "deploymentType": "prod",
    "createTime": 1760880185840,
    "projectId": 1209929
  }
]

Create Deploy Key

Create a deploy key for a deployment:

./scripts/create_deploy_key.py <deployment_name> <key_name>

Arguments:

• deployment_name: Name of the deployment (required, e.g., 'playful-otter-123')
• key_name: Name for the deploy key (required)

Example:

./scripts/create_deploy_key.py playful-otter-123 ci-deploy-key

Output format:

{
  "deployKey": "dev:playful-otter-123|ey..."
}

Note: When using OAuth tokens, the deploy key inherits OAuth permissions. Otherwise, a deployment-specific token is created.

API Reference

For complete Management API documentation, see api-reference.md.

Error Handling

Missing .env file:

Error: .env file not found in current directory or parent directories

Create a .env file at the project root with your CONVEX_TOKEN.

Missing token in .env:

Error: CONVEX_TOKEN not found in .env file

Add CONVEX_TOKEN=your_token to your .env file.

Invalid token:

HTTP Error 401: Unauthorized

Verify your token is correct and hasn't expired. Get a new token from the Convex Dashboard.