web-ext v7 command reference

--as-needed

Re-build the extension anytime you edit and save a source file. This allows you to continuously create a package with the most up to date source code.

Environment variable: $WEB_EXT_AS_NEEDED=true

--overwrite-dest, -o

Overwrite destination package file if it exists. Without this option, web-ext will exit in error if the destination file already exists.

Environment variable: $WEB_EXT_OVERWRITE_DEST=true

--filename, -n

Name of the created extension package file. In this option, the values defined in manifest.json can be used by enclosing them with { }. The default value is {name}-{version}.zip.

Environment variable: $WEB_EXT_FILENAME

--output, -o

The type of output to generate when reporting on errors. Choices: json or text.

Environment variable: $WEB_EXT_OUTPUT

--metadata

Output only metadata about the extension in JSON.

Environment variable: $WEB_EXT_METADATA=true

--pretty

Format the JSON output so that it's easier to read. This only applies when --output is set to json.

Environment variable: $WEB_EXT_PRETTY=true

--self-hosted

Declares that your extension will be self-hosted. This disables messages related to hosting on addons.mozilla.org.

Environment variable: $WEB_EXT_SELF_HOSTED=true

--boring

Disables colorful shell characters so that the output only contains plain text.

Environment variable: $WEB_EXT_BORING=true

--warnings-as-errors, -w

Treat warnings as errors by exiting non-zero for warnings.

Environment variable: $WEB_EXT_WARNINGS_AS_ERRORS=true

--firefox-preview

Turn on developer preview features in Firefox. This option accepts multiple values, depending on the available developer previews.

--adb-bin

Path to the ADB (Android Device Bridge) executable on the machine you are running web-ext from. By default, the adb executable will be located on your PATH.

Environment variable: $WEB_EXT_ADB_BIN

--adb-device, --android-device

The ID of your target Android device. If you do not specify this option, web-ext will list the IDs of each device connected. If you don't see a list of connected devices, make sure yours is set up for development.

Example:

web-ext run --target=firefox-android --android-device FA4AX0201736

Environment variable: $WEB_EXT_ADB_DEVICE

--adb-host

Host name to use when connecting to an Android device with ADB (Android Device Bridge). This will be discovered automatically by default.

Environment variable: $WEB_EXT_ADB_HOST

--adb-port

Network port to use when connecting to an Android device with ADB (Android Device Bridge). This will be discovered automatically by default.

Environment variable: $WEB_EXT_ADB_PORT

--adb-remove-old-artifacts

web-ext automatically removes all the temporary files that were written to the target adb device when it does exit. This may fail, for example when the device is disconnected before
web-ext run exited.

Starting from v5.0.0, web-ext run will automatically detect and warn the user if old artifacts have been found on the adb device, but it does not automatically remove them by default.

This flag forces web-ext to automatically remove these discovered artifacts.

Environment variable: $WEB_EXT_ADB_REMOVE_OLD_ARTIFACTS

--browser-console, -bc

This opens a Browser Console on startup, so you can see log messages for your extension. Example:

web-ext run --browser-console

Environment variable: $WEB_EXT_BROWSER_CONSOLE=true

Note: The browser console may not show all debugging output from content-scripts. Use the web console when debugging content-scripts.

--devtools

This opens the Developer Tools for the installed extension on startup. See this documentation for more information. Example:

web-ext run --devtools

Note: The opened Developer Tools may not show all debugging output from content-scripts. Use the web console when debugging content-scripts.

--firefox, -f

Specify a particular version of Firefox Desktop to run the extension in. The value is an absolute path to the Firefox executable or an alias string. If this is not specified, it will attempt to run the extension inside the system's default installation of Firefox.

Here is an example specifying a full path to a Firefox executable on Windows:

--firefox="C:\Program Files\Mozilla Firefox\firefox.exe"

Here is an example specifying an executable path on Mac OS:

--firefox=/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin

You can also use aliases, like this:

--firefox=beta

Here are all available aliases and the executables they map to:

As of web-ext 7.2.0, Flatpak users can use this option with the value flatpak:org.mozilla.firefox (where org.mozilla.firefox is the Flatpak application ID for Firefox on Flathub):

web-ext run --firefox=flatpak:org.mozilla.firefox

Environment variable: $WEB_EXT_FIREFOX

--firefox-apk

The exact APK name for Firefox on your Android device. Without specifying this option, web-ext will automatically select it for you. If more than one Firefox APK is installed, web-ext will show a list of values to choose from.

Example:

web-ext run --target=firefox-android --firefox-apk=org.mozilla.firefox

Environment variable: $WEB_EXT_FIREFOX_APK

--firefox-preview

Turn on developer preview features in Firefox. This option accepts multiple values, depending on the available developer previews.

--firefox-profile, -p

Specify a base Firefox profile to run the extension in. This is specified as a string containing your profile name or an absolute path to its directory. The profile you specify is copied into a new temporary profile and some settings are added that are required for web-ext to function.

If a profile is not specified, it runs the extension using a new temporary profile.

Environment variable: $WEB_EXT_FIREFOX_PROFILE

--profile-create-if-missing

With this option, the profile directory (specified by the --firefox-profile or --chromium-profile options) will be created if it does not exist yet.

Environment variable: $WEB_EXT_PROFILE_CREATE_IF_MISSING

--keep-profile-changes

With this option, any changes made to the profile directory (specified by --firefox-profile) are saved. Without this option, profile changes are not saved.

Environment variable: $WEB_EXT_KEEP_PROFILE_CHANGES=true

--no-reload

Do not automatically reload the extension in the browser as you edit and save source files.

Environment variable: $WEB_EXT_NO_RELOAD=true

--pre-install

Pre-install the extension into the profile before starting the browser. This is a way to support Firefox versions less than 49, as they don't support remote installation. Specifying this option implies --no-reload.

Environment variable: $WEB_EXT_PRE_INSTALL=true

--pref

Customize any Firefox preference without creating or modifying the profile. Use the equal sign to set values, for example:

--pref general.useragent.locale=fr-FR

Specify this option multiple times to set more than one preference.

Environment variable: $WEB_EXT_PREF

--target, -t

This specifies which application to run your extension in. Specify this option multiple times to run the extension in each application concurrently.

Here are the supported targets:

If no target is specified, the extension will run in firefox-desktop.

Environment variable: $WEB_EXT_TARGET

--args, --arg

Additional CLI options passed to the Browser binary. Example:

web-ext run --arg="--search=mozilla" --arg="--new-tab=https://duckduckgo.com"

web-ext run --arg="--remote-debugging-port=9229" --target chromium

--chromium-binary

Path or alias to a Chromium executable such as google-chrome, google-chrome.exe or opera.exe etc.
If not specified, the default Google Chrome will be used.

--chromium-profile

Path to a custom Chromium profile.

--start-url

This will open a tab at the specified URL when the browser starts. Example:

web-ext run --start-url www.mozilla.com

Declare this option multiple times to open multiple tabs. Example:

web-ext run --start-url www.mozilla.com --start-url developer.mozilla.org

Environment variable: $WEB_EXT_START_URL

--watch-file, --watch-files

A list of files that should be watched for changes. This is useful if you want web-ext to explicitly watch for changes to specific files, without watching the extension directory tree, e.g. the output of the build from a module bundler.

web-ext run --watch-file dist/background.js dist/content-script.js

--watch-ignored

A list of paths and globs patterns that should not be watched for changes. This is useful if you want to explicitly prevent web-ext from watching part of the extension directory tree, e.g. the node_modules folder.

web-ext run --watch-ignored dir1/to/file.js dir2/*.js dir3/**

--use-submission-api

Use the experimental addons.mozilla.org add-on submission API, rather than the addons.mozilla.org signing API to sign your extension. This allows listed versions to be freely created by enabling all necessary additional metadata to be submitted at the same time as the extension file.

With this option enabled, --channel changes to be a required option with no default. The choices remain listed and unlisted.

Environment variable: $WEB_EXT_USE_SUBMISSION_API

--api-key

Your API key (JWT issuer) for accessing the addons.mozilla.org API. This should always be a string.

Environment variable: $WEB_EXT_API_KEY

--api-secret

Your API secret (JWT secret) from addons.mozilla.org API. This should always be a string.

Environment variable: $WEB_EXT_API_SECRET

--api-url-prefix

The signing API URL prefix. This should always be a string. If not specified, this will default to https://addons.mozilla.org/api/v4 which is the production API.

Environment variable: $WEB_EXT_API_URL_PREFIX

--amo-base-url

The add-on submission API base URL. This should always be a string. If not specified, this will default to https://addons.mozilla.org/api/v5 which is the production API.

Environment variable: $WEB_EXT_AMO_BASE_URL

--api-proxy

A proxy host to use for all API connections. Example: https://yourproxy:6000.Read more about how proxy requests work. There is a separate section about signing in a restricted environment if the proxy approach doesn't work for you.

Environment variable: $WEB_EXT_API_PROXY

--channel

This specifies the channel in which the extension is signed. It defaults to unlisted or the channel of your extension's latest version. When the --use-submission-api option is specified the behaviour of --channel - and the limitations - are quite different than explained here: see the documentation for --use-submission-api above for more information.

The allowed values for channel are:

One example of using the --channel option is to create a beta version for a listed extension (that is, one you have already submitted to addons.mozilla.org).

See documentation on the signing API for more information.

Environment variable: $WEB_EXT_CHANNEL

--timeout

Number of milleseconds to wait before giving up on a response from Mozilla's web service. This should always be a number.

Environment variable: $WEB_EXT_TIMEOUT

--id

A custom identifier string for the extension. This has no effect if the extension already declares an identifier in its manifest. This option may be useful for signing versions of an existing extension that you own.

Environment variable: $WEB_EXT_ID

--amo-metadata

Path to a JSON file containing an object with metadata to be passed to the add-on submission API. Typically this is used to submit the required metadata for the first listed version of an extension (e.g. categories; license), but any supported JSON metadata can be supplied.

Environment variable: $WEB_AMO_METADATA