Skip to content
ExtensionStart Docs

CLI reference

create-extstart configures your clone in place. Run it from anywhere inside the clone; it finds the repo root itself. The full walkthrough is in the wizard guide.

Terminal window
pnpm create extstart [options]

Options

Section titled “Options”
flag meaning
--name "My Ext" extension name (written to site.config.ts, consumed by the manifest)
--description "..." one-line description
--scope minimal|everything module scope preset: minimal keeps billing, gate (plus dependencies) and the site template; everything keeps all optional modules (the --yes default)
--keep a,b,c optional modules to keep; the others are pruned. all (the default with --yes) and none also work. Overrides --scope
--browsers chrome|chrome+firefox target browsers
--billing-model <name> monetization model: subscription (default), lifetime-only, hybrid-credits, or credits-only. Rewrites site.config.ts pricing and defaults the gate preset; ignored when billing is dropped (payments guide)
--preset <name> gate preset: value-first, day-zero, metered, or silent. Ignored (with a note) when billing/gates are dropped
--keep-markers keep the module:* wiring markers so the wizard can prune again later; by default they’re stripped after the run (see below)
--firebase run only the Firebase setup step: no questionnaire, prune, or clean-tree requirement. Writes the project config everywhere it lives; safe to re-run. See the Sign-in guide
--firebase-project <id> Firebase project id to use non-interactively (with --firebase --yes)
--firebase-create with --firebase-project: create that project. Headless runs never create cloud resources without this explicit flag
--yes, -y non-interactive: accept flags/defaults, no prompts
--dry-run print the full plan, change nothing
--force run even with a dirty git working tree
--skip-verify skip the typecheck verify pass
--with-tests also run unit tests in the verify pass
--help, -h usage text

Module IDs for --keep

Section titled “Module IDs for --keep”

billing, gate, sidepanel, site, broadcasts, error-reporting, content-demo, demo-newtab, demo-devtools. Convenience aliases: gates → gate, billing-stripe → billing, errors → error-reporting.

Dependencies resolve automatically and loudly: --keep gates force-keeps billing (with a printed note); dropping billing drops gate and demo-newtab too.

Semantics worth knowing

Section titled “Semantics worth knowing”
  • Dirty-tree refusal: the wizard deletes and rewrites files, so it requires a clean git status; you review the result with git diff and undo with git. --force overrides; --dry-run never needs it.
  • --yes without --scope/--keep keeps every optional module.
  • Marker cleanup is the default: after pruning, every remaining module:* marker comment is stripped from the kept files (code stays). Pass --keep-markers if you want to re-run the wizard to prune more later; without them, a second pass can only rebrand, not prune.
  • --billing-model defaults the gate preset (metered for the credit models); an explicit --preset wins.
  • --dry-run --keep none prints the maximal prune plan, the fastest way to see everything the module system owns.
  • An existing apps/extension/.env is never overwritten by the env scaffold. The --firebase step is the one exception: it updates only VITE_FIREBASE_HOSTING_URL, WXT_API_URL (and, if you paste one, WXT_GOOGLE_OAUTH_CLIENT_ID) in place; every other line is preserved.
  • Exit code is non-zero when the wizard aborts, the plan is declined, or the verify pass fails typecheck, so it’s safe to use in CI.

Examples

Section titled “Examples”
Terminal window
# Full walkthrough with prompts
pnpm create extstart