Convex

Interact with your Convex projects directly from Raycast

Bobby Alv

New

Install Extension

Overview

Convex Tools for Raycast

Interact with your Convex projects directly from Raycast. Switch between projects, run functions, browse tables, view real-time logs, search documentation, and explore components without leaving your keyboard.

Features

Manage Projects

Quickly manage and switch between your Convex teams, projects, and deployments. Your selection is persisted across all commands.

Switch Deployment

Quick switcher for changing between dev, prod, and preview deployments within your current project. Perfect for when you need to quickly check something in a different environment.

Run Function

Search and execute your Convex queries, mutations, and actions:

Fuzzy search across all functions
JSON argument input with validation
View execution results with timing
Copy results to clipboard
Support for queries, mutations, and actions

Data

Explore your database tables and documents:

List all tables in your deployment
Paginated document browsing
View full document details with metadata panel
Collapsible raw JSON view (toggle with ⌘+J)
Enhanced field value formatting for timestamps, objects, and arrays
Copy document IDs and JSON
Search and filter documents

Logs

Stream real-time function execution logs with enhanced features:

Live log streaming from your deployment
Function call tree visualization showing parent-child relationships
Collapsible console output (toggle with ⌘+L)
Request-level filtering to view all executions in a request
Enhanced metadata showing execution environment, caller, and identity
Copy execution IDs
Filter by function name
View execution time, status, and errors
Pause/resume streaming

Search Docs

Quick access to Convex documentation:

Browse 60+ documentation articles
Organized by categories (Getting Started, Database, Functions, etc.)
Quick links to guides and API references
Search functionality

Components

Discover and install Convex components:

Browse 30+ available components
View component descriptions and features
Copy install commands
See npm download stats
Direct links to component repositories

Configure Deploy Key

Set up deploy key authentication for direct access to a specific deployment:

Alternative to OAuth browser login
Perfect for accessing a single deployment quickly
Validates credentials before saving
Easy disconnect option

Open Dashboard

Quickly open the current deployment in the Convex dashboard in your browser. No-view command for instant access.

Copy Deployment URL

Copy your current deployment URL to clipboard with a single command. Perfect for sharing or pasting into configuration files.

Installation

From Raycast Store (Recommended)

Open Raycast
Search for "Convex Tools"
Click Install

Manual Installation (Development)

Clone this repository
Navigate to extensions/convex
Run npm install or pnpm install
Run npm run dev to start development mode

Authentication

This extension supports two authentication methods:

Option 1: OAuth Login (Recommended for multiple projects)

Uses OAuth 2.0 Device Authorization Flow to securely authenticate with your Convex account.

How it works:

When you first use the extension, you'll see a "Sign in with Convex" button
Click to start authentication - a browser window will open
Complete the sign-in in your browser (you'll see a verification code)
Once authenticated, you'll have access to all your Convex projects

Security:

No client secrets are stored in the extension
Tokens are stored securely using Raycast's LocalStorage API
You can sign out at any time from any command

Option 2: Deploy Key (Recommended for single deployment access)

Use a deploy key for direct access to a specific deployment without browser login.

How to set up:

Method A: Using the Configure Deploy Key command (Recommended)

Open Raycast and search for "Configure Deploy Key"
Enter your Deploy Key (get from Convex Dashboard → Settings → Deploy Key)
Enter your Deployment URL (e.g., https://your-deployment.convex.cloud)
The credentials will be validated before saving

Method B: Using Extension Preferences

Open Raycast Preferences (⌘,)
Go to Extensions → Convex
Enter your Deploy Key and Deployment URL

Deploy Key Format:

Deploy Key: instance-name|0a1b2c3d4e5f... (from Dashboard → Settings → Deploy Key)
Deployment URL: https://instance-name.convex.cloud

Important Notes:

Deploy key mode locks you to a single deployment
You cannot switch between projects/deployments in deploy key mode
To switch projects, disconnect the deploy key first
BigBrain features (team/project selection) are not available with deploy keys

Usage

First Time Setup (OAuth)

Open Raycast and search for "Manage Projects"
Click "Sign in with Convex" to authenticate
Select your team, project, and deployment
You're ready to use all commands!

First Time Setup (Deploy Key)

Open Raycast and search for "Configure Deploy Key"
Enter your deploy key and deployment URL
Click "Save Configuration"
You're ready to use data, functions, and logs commands!

Switching Deployments

Open "Manage Projects" command
Navigate through Teams → Projects → Deployments
Select your desired deployment
All other commands will now use this deployment

Running Functions

Open "Run Convex Function" command
Search for your function by name or type
Enter JSON arguments (if needed)
Press Enter to execute
View and copy results

Browsing Tables

Open "Data" command
Select a table from the list
Browse documents with pagination
View full document details with metadata
Toggle raw JSON view with ⌘+J

Viewing Logs

Open "Logs" command
View real-time function execution logs
Toggle console output with ⌘+L
Filter by function name or request ID
View call trees and execution metadata

Searching Documentation

Open "Search Docs" command
Browse by category or search
Select an article to open in browser

Browsing Components

Open "Components" command
Browse available components
Copy install commands
Open component repositories

Keyboard Shortcuts

Action	Shortcut
Go back	`⌘ [`
Copy to clipboard	`⌘ C`
Copy JSON	`⌘ ⇧ C`
Open in Dashboard	`⌘ O`
Load more	`⌘ L`
Toggle console (Logs)	`⌘ L`
Toggle raw JSON (Data)	`⌘ J`

Troubleshooting

"No Deployment Selected"

Use the "Manage Projects" command to select a team, project, and deployment first. Or use "Configure Deploy Key" to set up deploy key authentication.

Authentication Issues

Try signing out and signing back in
Check that you have access to the team/project in the Convex Dashboard
Ensure your browser can reach auth.convex.dev

Deploy Key Issues

Verify the deploy key is correct (Dashboard → Settings → Deploy Key)
Make sure the deployment URL matches your deployment
Use "Configure Deploy Key" to validate and re-enter credentials

"BigBrain API error: 401 Unauthorized"

This error occurs when trying to use OAuth features with an invalid or expired token:

Sign out and sign back in
Or switch to deploy key mode if you only need access to one deployment

Functions Not Loading

Only public functions are shown
Internal functions (not exported) are hidden
Make sure your deployment has been pushed

API Errors

Check your network connection
Verify the deployment is accessible
Try switching to a different deployment

Development

This extension is part of the Convex Panel monorepo.

Structure

extensions/convex/
├── src/
│   ├── switch-project.tsx       # Manage Projects command
│   ├── switch-deployment.tsx    # Switch Deployment command
│   ├── run-function.tsx         # Run Function command
│   ├── data.tsx                 # Data browser command
│   ├── logs.tsx                 # Logs viewer command
│   ├── search-docs.tsx          # Search Docs command
│   ├── components.tsx           # Components browser command
│   ├── configure-deploy-key.tsx # Configure Deploy Key command
│   ├── open-dashboard.tsx       # Open Dashboard command
│   ├── copy-deployment-url.tsx  # Copy Deployment URL command
│   ├── lib/
│   │   ├── auth.ts              # OAuth device code flow
│   │   ├── api.ts               # Convex API client
│   │   ├── bigbrain.ts          # BigBrain API for teams/projects
│   │   ├── deployKeyAuth.ts     # Deploy key authentication
│   │   └── constants.ts         # Shared constants
│   ├── hooks/
│   │   ├── useConvexAuth.ts     # Authentication hook
│   │   └── useConvexData.ts     # Data fetching hooks
│   └── components/
│       ├── AuthGuard.tsx        # Authentication wrapper
│       ├── AuthenticatedListGuard.tsx
│       └── DeploymentSelector.tsx
├── assets/
│   ├── command-icon.png
│   └── extension-icon.svg
├── metadata/
│   ├── convex-1.png             # Screenshots
│   ├── convex-2.png
│   └── convex-3.png
├── package.json
└── README.md

Running Locally

cd extensions/convex
npm install
npm run dev

Building

npm run build

Contributing

Contributions are welcome! Please read the contributing guidelines in the main repository.

License

MIT