Start command for build-and-launch workflow

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

Capability	What it gives you
Build + launch workflow	Run production compile and browser launch in one step
Target selection	Start directly in selected browser or engine target
Runner control	Skip browser launch when you only need build verification
Production-like validation	Check real compiled output instead of watch-mode state

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

extension start [path-or-url] [options]

extension start [path-or-url] [options]

extension start [path-or-url] [options]

extension start [path-or-url] [options]

extension start [path-or-url] [options]

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

Arguments and flags

Flag	Alias	What it does	Default
`[path or url]`	-	Extension path or remote URL.	`process.cwd()`
`--browser <browser>`	-	Browser/engine target.	`chromium`
`--profile <path\|boolean>`	-	Browser profile path or boolean profile mode.	fresh profile
`--chromium-binary <path>`	-	Custom Chromium-family binary path.	system default
`--gecko-binary <path>`	`--firefox-binary`	Custom Gecko-family binary path.	system default
`--polyfill [boolean]`	-	Enable `browser.*` API compatibility polyfill for Chromium targets.	`true`
`--starting-url <url>`	-	Starting URL in launched browser.	unset
`--no-browser`	-	Build but skip browser launch.	browser launch enabled
`--wait [boolean]`	-	Wait for `dist/extension-js/<browser>/ready.json` and exit.	disabled
`--wait-timeout <ms>`	-	Timeout for `--wait` mode.	`60000`
`--wait-format <pretty\|json>`	-	Output format for wait results (`json` is machine-readable).	`pretty`
`--port <port>`	-	Runner/devtools port when runner is enabled. Use `0` for OS-assigned port.	`8080`
`--host <host>`	-	Host to bind the dev server to. Use `0.0.0.0` for Docker/dev containers.	`127.0.0.1`
`--public-host <host>`	-	Connectable host the browser dials when it differs from the bind `--host` (remote/dev container).	bind host (`127.0.0.1` when bound to `0.0.0.0`)
`--extensions <list>`	-	Comma-separated companion extensions or store URLs.	unset
`--install [boolean]`	-	Install project dependencies when missing.	command behavior default
`--author`	`--author-mode`	Enable maintainer diagnostics.	disabled

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.

`--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:

Run extension start --no-browser as the producer process.
Run extension start --wait --browser=<browser> as the readiness gate.
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). If you pass both --wait and --no-browser in the same invocation, --wait takes precedence. The command runs in wait-only mode.

Logging flags

Flag	What it does	Default
`--logs <off\|error\|warn\|info\|debug\|trace\|all>`	Minimum log level.	`off`
`--log-context <list\|all>`	Context filter (`background`, `content`, `page`, `sidebar`, `popup`, `options`, `devtools`).	`all`
`--log-format <pretty\|json\|ndjson>`	Logger output format.	`pretty`
`--no-log-timestamps`	Disable timestamps in pretty mode.	timestamps enabled
`--no-log-color`	Disable color in pretty mode.	color enabled
`--log-url <pattern>`	Filter log events by URL substring/regex.	unset
`--log-tab <id>`	Filter log events by tab ID.	unset

Shared global options

Also supports Global flags.

Examples

Start with default browser

extension start

extension start

extension start

extension start

extension start

Start in Firefox

extension start --browser firefox

extension start --browser firefox

extension start --browser firefox

extension start --browser firefox

extension start --browser firefox

Build and skip browser launch

extension start --no-browser

extension start --no-browser

extension start --no-browser

extension start --no-browser

extension start --no-browser

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.

Next steps

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

Dev command for watch mode and live reload Preview command to launch built extensions

⌘I

​When to use start

​Start command capabilities

​How it differs from other commands

​Usage

​Arguments and flags

​Automation metadata

​--no-browser and readiness synchronization

​Logging flags

​Shared global options

​Examples

​Start with default browser

​Start in Firefox

​Build and skip browser launch

​Behavior notes

​Next steps