CLI & Migrations - Vextro Docs

Available Commands

Command	Description
`vextro-init`	Scaffold a new admin app with templates and Convex schema
`vextro-sync`	Auto-generate the admin exports block in `convex/admin.ts`
`vextro-migrate`	Detect schema changes and generate migration plans

vextro-init

Scaffolds Astro pages, Convex tables, and admin config into your app.

npx vextro-init --app apps/admin --path /admin

What it does: copies Astro templates into apps/<app>/src/, copies Convex helpers into convex/, patches convex/schema.ts to spread ...vextroTables, and updates basePath in admin config.

Flag	Description	Default
`--app <path>`	Target app directory	Prompted
`--path <base>`	URL base path for admin UI	`/`
`--force`	Overwrite existing files	`false`

vextro-sync

Auto-generates the admin exports block inside your convex/admin.ts file. Run this after adding or removing collections so that Vextro's generated function list stays in sync with your collection definitions.

npx vextro-sync

What it does: reads the VEXTRO_ADMIN_FUNCTION_NAMES constant from the Vextro package and rewrites the export list between the // vextro-exports-start and // vextro-exports-end marker comments in your admin file. It leaves all other content in the file untouched.

Flag	Description	Default
`--admin-file <path>`	Path to the admin module file	`convex/admin.ts`
`--variable-name <name>`	Name of the admin module variable	`admin`
`--quiet`, `-q`	Suppress all console output	`false`

When to run

Run vextro-sync any time you:

Add a new collection to your admin config
Remove a collection from your admin config
Upgrade the vextro package to a version that adds or removes generated functions

Example

# Use defaults (reads convex/admin.ts, variable name "admin")
npx vextro-sync

# Point to a non-standard file path
npx vextro-sync --admin-file apps/admin/convex/admin.ts

# Suppress output (useful in CI)
npx vextro-sync --quiet

If the marker comments are missing from the target file, the command exits with a non-zero status and prints an error. Add the markers manually before running sync:

// convex/admin.ts
export const admin = createVextroAdminModule({ /* ... */ });

// vextro-exports-start
// vextro-exports-end

vextro-migrate

Detects differences between collection definitions and the live Convex schema.

npx vextro-migrate --check    # dry run
npx vextro-migrate --apply    # execute changes

Flag	Description
`--check`	Print diff without applying
`--apply`	Apply the migration plan
`--collection <slug>`	Scope to a single collection
`--verbose`	Show detailed field-level diffs

Migration Strategies

Strategy	When Used	Behavior
Additive	New fields or indexes	Adds to schema; existing data unaffected
Backfill	New required fields	Sets default values on existing documents
Rename	Field name change detected	Copies data from old to new field
Destructive	Field or table removal	Requires `--force`; never auto-runs

Metadata sharding guardrails

The vextro-migrate --check path uses the same metadata preflight guardrails as the admin module cutover flow.

Deep metadata branches are encoded once they exceed the storage budget, then certified against the persisted depth ceiling.
Canonical metadata is partitioned into shards and rejected if a projected shard or the combined payload crosses the byte thresholds.
Cycle detection and other hard preflight errors block --apply before any slot flip happens.

Use the preflight output to reduce schema depth or shrink oversized block metadata before running a cutover.

Example Output

$ npx vextro-migrate --check
Schema diff for "posts":
  + field "excerpt" (text, optional)
  + index "by_category" (category)
Plan: 2 additive changes. Run with --apply to execute.

CI Integration

Add a schema check to catch drift early. Exits non-zero on unapplied changes.

- run: npx vextro-migrate --check