pi-convex

Pi extension for Convex - manage queries, mutations, deployment, and learns about your project automatically.

Quick Start

pi install npm:pi-convex

Then in Pi:

1. /convex-init           # Create new project OR
1. /convex-connect        # Connect to existing project
2. convex_deploy          # Deploy!

Commands

| Command | Description | |---------|-------------| | /convex-init | Create a new Convex project (non-interactive, CI-friendly) | | /convex-connect | Add/switch connection (includes deploy key auth) | | /convex-connections | List all connections | | /convex-setup | Install ESLint plugin |

Tools

| Tool | Description | |------|-------------| | convex_query | Execute query: {"path": "tasks/list"} | | convex_mutation | Execute mutation: {"path": "tasks/create", "args": "{\"title\":\"Test\"}"} | | convex_dev | Run dev server (use {"once": true} for single deploy) | | convex_deploy | Deploy to production (auto-detects CI) | | convex_functions | List all functions + save to memory | | convex_status | Show connection and project status | | convex_schema_validate | Analyze schema for best practices | | convex_lint | Run ESLint (auto-installs plugin) | | convex_best_practices | Show Convex best practices | | convex_dashboard | Open dashboard in browser |

Authentication

Interactive Mode (via /convex-connect)

/convex-connect
→ Connection name: my-app
→ Is local? No
→ Use anonymous mode? No
→ Deploy key: (paste from dashboard.convex.dev)

Anonymous Mode (CI Agents)

For CI agents that can't authenticate:

/convex-connect
→ Use anonymous mode? Yes

This sets CONVEX_AGENT_MODE=anonymous for all commands.

CI Mode (Env Vars)

CONVEX_DEPLOY_KEY='your-key' convex_deploy

Create New Project

Note: Creating cloud projects requires being logged in to Convex CLI (npx convex login). If not logged in, use anonymous mode for local development only.

Interactive

/convex-init
→ Project name: my-app
→ Team name (from convex.cloud): my-team
→ Cloud deployment? Yes

Non-Interactive / CI

# Requires: npx convex login (done once per machine)
CONVEX_PROJECT_NAME=my-app CONVEX_TEAM_NAME=my-team /convex-init

Creates project with:

• npx convex dev --configure new --typecheck=disable --project <name> --team <team> --dev-deployment cloud
• Auto-configures as active project
• Auto-saves connection

Connect to Existing Project

/convex-connect
→ Connection name: my-app
→ Is local? No
→ Use anonymous mode? No
→ Deploy key: (from dashboard.convex.dev)

Multiple projects? Each project has its own deploy key. Save different connections with /convex-connect. The extension auto-detects the project from the current directory.

Usage Examples

# Create new project
/convex-init

# Connect to existing
/convex-connect

# Query all clients
convex_query with {"path": "clients/list"}

# Create a record
convex_mutation with {"path": "tasks/create", "args": "{\"title\":\"New task\"}"}

# Deploy (interactive)
convex_deploy

# Deploy (CI/non-interactive)
convex_deploy with {"projectName": "my-project", "teamName": "my-team"}

# List functions
convex_functions

# Run lint
convex_lint

# Check status
convex_status

CI / Non-Interactive Mode

The extension auto-detects non-interactive terminals (CI, scripts, etc.) and uses optimal flags:

# Auth via environment
CONVEX_DEPLOY_KEY='your-key' convex_deploy

# Anonymous mode (no auth needed)
CONVEX_AGENT_MODE=anonymous convex_deploy

Memory

The extension automatically learns:

1. Tables - From schema analysis
2. Functions - From convex_functions
3. Patterns - From lint results

Access via /skill:convex to see learned context.

Files

Settings stored in:

• ~/.pi/agent/extensions/pi-convex/config.json - Connections + deploy keys
• ~/.pi/agent/extensions/pi-convex/project.json - Project path
• ~/.pi/agent/extensions/pi-convex/memory.json - Learned context

Troubleshooting

| Problem | Solution | |---------|----------| | "No project" | cd to a Convex project directory | | "No connection" | Run /convex-connect | | Auth issues in CI | Set CONVEX_DEPLOY_KEY env var | | Anonymous mode for CI | Use /convex-connect and select "Yes" to anonymous | | Deploy interactive blocked | Use convex_deploy with projectName and teamName | | ARM64 deploy fails | Use npx convex deploy --typecheck=disable (no local dev) |

License

MIT