Setup with CLI

This is the main setup flow for buyers.

Prerequisites

• Node.js 20+
• Internet connection
• Accounts on:
  • Convex
  • Vercel

1) Run setup

From the project folder:

npm install
npm run setup

The wizard will ask questions in the terminal and run commands for you.

---

2) Prompt-by-prompt guide

Choose your Vercel project slug

Example: my-portfolio

• This becomes your default URL: https://my-portfolio.vercel.app
• Use lowercase letters, numbers, and -
• If Vercel assigns a different URL (name already taken), setup auto-detects it, syncs URLs, and asks to redeploy.

Use a custom production domain?

• N if you want to use Vercel default domain
• Y if you already own a domain (example https://portfolio.example.com)
• If the custom domain is not ready yet, use N first and switch later in Vercel + Convex.

Generate BETTER_AUTH_SECRET automatically?

• Recommended: Y
• If N, paste your own secret (32+ characters)

Enter NEXT_PUBLIC_CONVEX_URL (.convex.cloud)

Where to find it:

1. Open Convex dashboard
2. Open your project
3. Go to Settings (Production deployment) or Deployments → Production
4. Copy the Cloud URL (ends with .convex.cloud)

Example: https://my-project.eu-west-1.convex.cloud

This URL is used for your live site (Vercel). Setup also derives your Development deployment name from it for convex dev --once. If linking fails, copy the Development Cloud URL instead (Deployments → Development) and use that hostname’s project slug.

Enter NEXT_PUBLIC_CONVEX_SITE_URL (.convex.site)

Where to find it:

1. Open Convex dashboard
2. Open your project
3. Go to Settings
4. Copy the value under the label HTTP Actions URL (ends with .convex.site)

Example: https://my-project.eu-west-1.convex.site

Important:

• Must end with .convex.site
• Do not paste your Vercel URL here

Enter CONVEX_DEPLOY_KEY

Where to find it:

1. Open Convex dashboard
2. Project → Settings → Deploy Key
3. Create/copy key and paste in terminal

---

3) Commands the wizard can run

The wizard asks before running each step:

• npx convex login
• write CONVEX_DEPLOYMENT=dev:… to .env.local
• npx convex env set SITE_URL … --prod and BETTER_AUTH_SECRET (Production — your live app)
• npx convex env set SITE_URL http://localhost:3000 (Development — before first push)
• npx convex env set BETTER_AUTH_SECRET … (Development)
• npx convex dev --once (syncs Development only; updates .env.local)
• npx vercel login
• npx vercel link
• set Vercel env vars (production, optional preview)
• npx vercel --prod

If a step fails, fix the issue and run npm run setup again.

---

4) After deploy

When setup succeeds:

1. Open your live URL
2. Open /admin/seed
3. Create your first admin user
4. Login at /admin
5. Go to /admin/settings and disable /admin/seed

Then continue with after-setup.md.

If the first deploy fails and the log shows a different *.vercel.app URL than expected, the wizard now updates:

• Vercel NEXT_PUBLIC_SITE_URL
• Convex SITE_URL

and asks to redeploy automatically.