Skip to main content
Use start when you want a production build and immediate browser launch in one command. The start command runs a production build first, then launches the built extension using the same flow as the preview command.

When to use start

  • Manually validating production behavior right after compilation.
  • Reproducing runtime differences between watch mode and production output.
  • Running a production-like check locally without a separate build then preview step.

Start command capabilities

How it differs from other commands

  • dev: dev server + hot module replacement (HMR)/watch mode
  • build: production build only
  • preview: launch an existing built extension without building
  • start: build + preview in sequence

Usage

If you omit the path, the command uses the current working folder.

Arguments and flags

On Firefox, --starting-url opens after the add-on installs, so your document_start content scripts run on that page. From the release after 4.1.39, it no longer replaces a tab that your extension opened. Two deprecated aliases are hidden from --help but still work:
  • --wait-format <pretty|json> maps onto --output and warns once on stderr. Migrate scripts to --output.
  • --author and --author-mode map onto --debug.

Browser support

start has no Safari path. Passing --browser safari (or webkit-based) exits with E_COMMAND_UNSUPPORTED_FOR_TARGET. The reason is measured. Safari’s WebDriver route does load an unpacked folder, and the background even runs, but Safari grants the extension zero host origins. Content scripts never inject, and no API call can grant the access afterwards. Use dev or build for Safari targets. start also refuses chromium-emulator and exits with E_UNSUPPORTED_BROWSER. The emulated Chromium page reads your build from the dev server, which start does not run. Use dev for that target.

Automation metadata

start writes readiness metadata to:
  • dist/extension-js/<browser>/ready.json
This is useful for automation when using --no-browser:
  • Wait for status: "ready" before launching external runners.
  • Handle status: "error" as a deterministic failure signal.
  • Use runId and startedAt to correlate a specific runtime session.
From the release after 4.1.41, sessions started at the same time each get their own debugging port. Read cdpPort or rdpPort from ready.json instead of assuming 9222. cdpPort is on the record when the card prints. From the release after 4.1.39, with --allow-control or --allow-eval, the status stays starting until the extension’s background connects or 10 seconds pass. Read executorAttachedAt to know that an act verb can run. See the ready.json contract. From the release after 4.1.39, a refusal from such a session names extension start as the command to restart. A build with no background script or service worker cannot be controlled: the session warns at startup, and every act verb answers that the build has no background. See Refusals on a start or preview session. After the session ends, an act verb says so and prints the extension start command that starts it again. See When the session has ended.

Stop the browser from launching

Two flags sound alike and do different things:
--no-browser also has a config form, commands.start.noBrowser: true, and an environment form, EXTENSION_CLI_NO_BROWSER=1. dev, start, and preview all accept both flags. From the release after 4.2.0, the card of start --no-browser marks its Browser row (no-browser mode), as dev and preview do.

--no-browser and readiness synchronization

--no-browser only disables browser launch. It does not block external runners until the production build finishes. For production-oriented Playwright, continuous integration (CI), and AI workflows:
  1. Run extension start --no-browser as the producer process.
  2. Run extension start --wait --browser=<browser> as the readiness gate.
  3. Launch external browser automation only after status: "ready".
--wait exits non-zero on error/timeout and ignores stale contracts from dead processes (pid no longer alive). Because start can finish quickly, a contract from a completed run still counts when its timestamp is within a 60 second window. --wait requires a local project path. Passing a remote URL exits with E_ARGS. Passing both --wait and --no-browser in the same invocation exits with E_INVALID_OPTION, because --wait only reads a contract that another process writes. Run them as two processes, as in the steps above.

Machine output with --output json

--output json prints schema-1 envelopes on stdout, one JSON object per line:
  • A plain start run prints one status: "started" frame once the build finished and the browser launched. It carries the project path, browser list, pid, and port: null, because a run-only session binds no port. A run that fails prints only its failure frame, never a started frame before it.
  • From the release after 4.2.0, SIGINT or SIGTERM ends the stream with one stopped frame that carries E_INTERRUPTED, value.signal, and value.browsers, and the run exits 0. A signal that lands while the build still runs ends it with the same frame, and the run exits 130 or 143. See Lifecycle stream.
  • A start --wait run prints one status: "ready" frame on success. Its value.results array carries the full ready contract per browser.
  • A start --wait run that reads a contract in error status prints one ok: false frame that names the cause, for example E_BROWSER_LAUNCH when the browser never started or E_BROWSER_EXITED when it exited. See the ready.json contract for the full list.
  • A failed build prints one ok: false frame with status: "build-failed" before the process exits 1. A compile error carries error.code: "E_COMPILE". A missing project folder carries E_PROJECT_NOT_FOUND, a folder with no manifest carries E_MANIFEST_NOT_FOUND, and a manifest that does not parse carries E_MANIFEST_INVALID. A config file that fails to load carries E_CONFIG_LOAD, and a remote URL that gives no usable archive carries E_REMOTE_ZIP_INVALID, E_REMOTE_FETCH_TIMEOUT, E_REMOTE_ACCESS_DENIED, or E_REMOTE_DOWNLOAD.
  • A bad --chromium-binary or --gecko-binary pin prints one ok: false frame with status: "usage" and error.code: "E_BROWSER_BINARY_INVALID". That covers a path that does not exist, a file that is not executable, and a binary that does not answer its version probe within 10 seconds. The command ends and leaves nothing running.
  • A browser that cannot start prints one ok: false frame with status: "failed". The code is E_BROWSER_LAUNCH when the binary is executable but the system cannot start it or Firefox exits before its debugger answers, and E_BROWSER_CONNECT when Firefox runs but its debugger never answers.
  • From the release after 4.1.41, a browser that refuses to load the extension prints one ok: false frame with status: "load-refused" and error.code: "E_EXTENSION_LOAD_REFUSED". start stops the browser and exits 1. A start --wait against that run answers the same status and code. See Manifest refusals.

Logging flags

These flags are experimental and may change between minor releases.

Shared global options

Also supports Global flags.

Examples

Start with default browser

Start in Firefox

Build and skip browser launch

Behavior notes

  • start does not run a dev server and does not provide hot module replacement (HMR) or watch mode.
  • start is production-mode oriented. Use dev for iterative local development.
  • For machine consumers, parse dist/extension-js/<browser>/ready.json instead of terminal text.
  • From the release after 4.1.41, if the browser refuses the extension, start stops the browser and exits with code 1. See Manifest refusals.

Next steps

  • Iterate quickly with dev.
  • Launch existing build output with preview.