Skip to main content

Command line

The better-convex-nuxt commands for development, the Convex CLI, and authentication setup.

The module installs the better-convex-nuxt command. Run it with pnpm exec better-convex-nuxt, or from a package.json script.

bash
better-convex-nuxt dev [nuxt dev options]
better-convex-nuxt convex <command> [options]
better-convex-nuxt auth init [--typed-client] [--yes] [--site-url <origin>]
better-convex-nuxt auth schema --config <schema-options.ts> [options]
better-convex-nuxt --version
The unscoped npm package better-convex is a different project. Do not run npx better-convex: it downloads that package instead of this command.

dev

dev runs convex dev and nuxt dev together, with [convex] and [nuxt] in front of each line. Ctrl-C stops both, and when one of them stops, dev stops the other.

package.json
{
  "scripts": {
    "dev": "better-convex-nuxt dev"
  }
}
  • Without a deployment in .env.local, Convex starts a local backend that needs no account (convex dev --anonymous). The first run downloads the backend and writes the deployment to .env.local.
  • With a deployment in .env.local, dev uses it. It must be a development, local, or anonymous deployment.
  • Nuxt starts when .env.local has the deployment URL. It gets CONVEX_URL, CONVEX_SITE_URL and your own values from .env.local (such as SITE_URL) on top of its .env, but not the deployment selector or keys.
  • Options after dev go to nuxt dev, for example better-convex-nuxt dev --port 3001.

A local backend has its dashboard on your machine. Open it with:

bash
pnpm exec better-convex-nuxt convex dashboard

auth init

auth init sets up authentication for a development deployment. It writes the auth files, generates the auth schema, and sets the development secrets and the first signing key. See add authentication for each step.

OptionEffect
--typed-clientAlso write app/convex-auth.ts
--yes, -yDo every step without asking. Use it in scripts and CI.
--site-url <origin>The development site URL. Without it, the default is http://localhost:3000.

auth init refuses a production deployment, also with --yes. It stops without changes when a file exists with other content. Running it again is safe.

Without --yes, auth init reads each answer from standard input, so you can also pipe answers:

bash
printf 'y\ny\n\ny\n' | pnpm exec better-convex-nuxt auth init

convex

convex runs the Convex CLI that is installed in the project. It reads the deployment only from .env.local and removes every other Convex setting from the environment, so a command cannot reach another deployment by accident.

CommandDeployment
convex devA development, local, or anonymous deployment
convex dev --anonymousA new anonymous local deployment
convex deployA production deploy key or a self-hosted backend
convex codegen, env, runThe deployment in .env.local
convex logs, convex dataThe deployment in .env.local
convex dashboardThe deployment in .env.local
convex configureChoose a deployment interactively
convex deployment select <selector>Choose a deployment by name

Other options pass through to the Convex CLI. Options that choose a different deployment, such as --prod, --url, or --deployment, fail before the Convex CLI starts.

Code generation without a cloud deployment

convex codegen writes convex/_generated/ from the deployment in .env.local. It reads the components from that deployment, so it always needs one. Convex has no code generation without a deployment.

A local deployment is enough, and it needs no account and no network after the first run:

bash
# Once: create an anonymous local deployment and write it to .env.local.
pnpm exec better-convex-nuxt convex dev --anonymous
# Then, after you add a module or an export:
pnpm exec better-convex-nuxt convex codegen

When the local backend is not running, convex codegen starts it for the run and stops it after. The first convex dev --anonymous downloads the backend; later runs use the downloaded copy.

bash
pnpm exec better-convex-nuxt convex logs --history 20
pnpm exec better-convex-nuxt convex data messages --limit 10

auth schema

auth schema generates convex/betterAuth/schema.ts and schemaMetadata.ts from your Better Auth plugin list. auth init runs it for you. Run it again after you change convex/betterAuth/schemaPlugins.ts. See Better Auth plugins.