Manage Better Auth user data in Convex component tables. Use when: (1) need to manually verify user email in development, (2) "Email not verified" error blocking login, (3) need to modify Better Auth user/session/account data directly, (4) can't write mutations to access component tables, (5) debugging auth issues in Convex + Better Auth setup. Covers CLI data access, export/import workflow, and common gotchas.
Better Auth stores user data in Convex component tables that can't be accessed through normal Convex queries/mutations. When you need to manually verify a user's email, modify auth data, or debug authentication issues, standard approaches don't work.
List available tables in the component:
npx convex data --component betterAuth
Common tables: user, session, account, verification
npx convex data user --component betterAuth --limit 20
As JSON for processing:
npx convex data user --component betterAuth --format jsonl > users.jsonl
Since you can't write mutations to access component tables directly, use export/import:
# Export current data
npx convex data user --component betterAuth --format jsonl > /tmp/ba-users.jsonl
# Modify the file (e.g., set emailVerified: true)
sed -i 's/"emailVerified": false/"emailVerified": true/g' /tmp/ba-users.jsonl
# Or for a specific user:
sed -i 's/"email": "[email protected]", "emailVerified": false/"email": "[email protected]", "emailVerified": true/g' /tmp/ba-users.jsonl
# Reimport (replaces all data in the table)
npx convex import --component betterAuth --table user --replace /tmp/ba-users.jsonl --yes
In your Better Auth config (e.g., convex/betterAuth.ts):
emailAndPassword: {
enabled: true,
requireEmailVerification: process.env.NODE_ENV === "production",
// ...
}
Note: This only affects NEW signups. Existing unverified users still need manual verification.
After modification:
npx convex data user --component betterAuth | grep "[email protected]"
Verify emailVerified shows true, then try logging in again.
Scenario: User signed up but email verification failed. Need to verify manually.
# Check current state
npx convex data user --component betterAuth --format pretty | grep -A2 "[email protected]"
# Shows: emailVerified: false
# Export, modify, reimport
npx convex data user --component betterAuth --format jsonl > /tmp/users.jsonl
sed -i 's/"email": "[email protected]", "emailVerified": false/"email": "[email protected]", "emailVerified": true/g' /tmp/users.jsonl
npx convex import --component betterAuth --table user --replace /tmp/users.jsonl --yes
# Verify
npx convex data user --component betterAuth | grep "[email protected]"
# Shows: emailVerified: true
--replace flag deletes all existing rows before import.
Export the full table first, modify, then reimport.ctx.db.query("betterAuth:user") won't work from your app's mutations.session and account tables if you
need to debug auth sessions.1x00000000000000000000AA
to bypass CAPTCHA in automated testing/development.ADMIN_EMAIL env var to automatically grant admin to that
user on first login sync.