CLI
Generate cRPC metadata with the better-convex CLI.
Overview
The better-convex CLI generates meta.ts with metadata for all your cRPC functions:
| Feature | Description |
|---|---|
| Metadata generation | Auto-generate meta.ts with function types |
| Auth-aware skipping | Enable query skipping based on auth state |
| Type-safe references | Get full type safety for function references |
| Custom metadata | Extract .meta() values from procedures |
| Environment sync | Sync env vars to Convex deployment |
Let's explore each command.
Installation
bun add better-convexCommands
dev
Run Convex dev server with automatic metadata generation:
npx better-convex devOptions:
| Flag | Description |
|---|---|
--meta <dir> | Output directory for meta.ts (default: convex/shared) |
This wraps convex dev and:
- Generates
meta.tsin the specified directory on startup - Watches for file changes and regenerates automatically
- Passes all other flags through to
convex dev
# With Convex flags
npx better-convex dev --oncecodegen
Generate meta.ts once (without watch mode):
npx better-convex codegenOptions:
| Flag | Description |
|---|---|
--meta <dir> | Output directory (default: convex/shared) |
--debug | Show detailed output |
--silent | Suppress all output |
env
Manage environment variables:
# Sync all vars from convex/.env
npx better-convex env sync
# With Better Auth: generate BETTER_AUTH_SECRET and JWKS
npx better-convex env sync --auth
# Force overwrite existing values
npx better-convex env sync --force
# Production deployment
npx better-convex env sync --prodOptions:
| Flag | Description |
|---|---|
--auth | Generate BETTER_AUTH_SECRET and JWKS (for Better Auth users) |
--force | Overwrite existing values (default: skip if up to date) |
--prod | Sync to production deployment |
The sync command:
- Reads all variables from
convex/.env - Syncs all variables to Convex (skips if already up to date)
- With
--auth: generatesBETTER_AUTH_SECRETandJWKSif missing
Requires npx better-convex dev running in background.
Other env subcommands pass through to Convex CLI:
npx better-convex env list
npx better-convex env get <name>
npx better-convex env set <name> <value>
npx better-convex env remove <name>Output
The CLI generates meta.ts at convex/shared/meta.ts by default.
// This file is auto-generated by better-convex
// Do not edit manually. Run `better-convex codegen` to regenerate.
export const meta = {
posts: {
list: { type: 'query' },
get: { auth: 'optional', type: 'query' },
create: { auth: 'required', type: 'mutation' },
},
users: {
me: { auth: 'required', type: 'query' },
},
} as const;
export type Meta = typeof meta;Metadata Extraction
The CLI uses TypeScript AST parsing to extract metadata from your cRPC procedures.
Supported Patterns
// Base procedure auth is detected
export const list = publicQuery.query(...); // auth: undefined
export const me = authQuery.query(...); // auth: 'required'
export const profile = optionalAuthQuery.query(...); // auth: 'optional'
// Function type is detected
export const get = publicQuery.query(...); // type: 'query'
export const create = publicMutation.mutation(...); // type: 'mutation'
export const sync = publicAction.action(...); // type: 'action'
// .meta() is extracted
export const admin = authQuery
.meta({ role: 'admin' })
.query(...); // { auth: 'required', role: 'admin', type: 'query' }Base Procedure Mapping
| Base Procedure | Auth Type |
|---|---|
publicQuery | undefined |
publicMutation | undefined |
publicAction | undefined |
optionalAuthQuery | 'optional' |
optionalAuthMutation | 'optional' |
authQuery | 'required' |
authMutation | 'required' |
authAction | 'required' |
Configuration
The CLI reads from convex.json:
{
"functions": "convex"
}The functions field specifies the Convex functions directory (default: convex).
Path Aliases
Add a path alias to import meta.ts:
{
"compilerOptions": {
"paths": {
"@convex/meta": ["./convex/shared/meta.ts"]
}
}
}Then import:
import { meta } from '@convex/meta';