web-ext command reference
This page lists all the commands and options available under the web-ext command line tool.
This page lists all the commands and options available under the web-ext command line tool.
web-ext has the following commands; options specific to these commands are included as subsections.
Packages an extension into a
.zip file, ignoring files that are commonly unwanted in packages, such as
.git and other artifacts. The name of the
.zip file is taken from the name field in the extension manifest.
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.
Overwrite destination package file if it exists. Without this option, web-ext will exit in error if the destination file already exists.
Opens the web-ext documentation in the user's default browser.
Reports errors in the extension manifest or other source code files. When
strict_min_version is set in your extension’s manifest file, lint will report on the permissions, manifest keys, and web extension APIs used that are not available in that version. See the addons-linter project for more information about what kind of rules are used to validate extension source.
The type of output to generate when reporting on errors. Choices:
Output only metadata about the extension in JSON.
Format the JSON output so that it's easier to read. This only applies when
--output is set to
Declares that your extension will be self-hosted. This disables messages related to hosting on addons.mozilla.org.
Disables colorful shell characters so that the output only contains plain text.
Treat warnings as errors by exiting non-zero for warnings.
Builds and then temporarily installs an extension on the target application, so it can be tested. By default, watches extension source files and reload the extension in each target as files change.
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
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.
web-ext run --target=firefox-android --android-device FA4AX0201736
Host name to use when connecting to an Android device with ADB (Android Device Bridge). This will be discovered automatically by default.
Network port to use when connecting to an Android device with ADB (Android Device Bridge). This will be discovered automatically by default.
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.
This opens a Browser Console on startup, so you can see log messages for your extension. Example:
web-ext run --browser-console
Note: The browser console may not show all debugging output from content-scripts. Use the web console when debugging content-scripts.
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:
You can also use aliases, like this:
Here are all available aliases and the executables they map to:
||The release build of Firefox|
||The beta build of Firefox|
||The nightly build of Firefox|
||The developer build of Firefox|
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.
web-ext run --target=firefox-android --firefox-apk=org.mozilla.firefox
Turn on developer preview features in Firefox. This option accepts multiple values, although it currently only supports the
mv3 value, which is also the default value.
mv3 value allows developers to test their extensions with Firefox Manifest Version 3 support (without having to manually flipping the related preferences).
This option was added in web-ext 7.1.0.
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.
With this option, the profile directory (specified by the
--chromium-profile options) will be created if it does not exist yet.
When this option is specified, the
--firefox-profile option is always treated as a directory path.
With this option, any changes made to the profile directory (specified by
--firefox-profile) are saved. Without this option, profile changes are not saved.
This option makes the profile specified by
--firefox-profile completely insecure for daily use. It turns off auto-updates and allows silent remote connections, among other things. Specifically, it will make destructive changes to the profile that are required for
web-ext to operate.
Do not automatically reload the extension in the browser as you edit and save source files.
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
Customize any Firefox preference without creating or modifying the profile. Use the equal sign to set values, for example:
Specify this option multiple times to set more than one preference.
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:
||The extension will run in Firefox Desktop.|
||The extension will run in Firefox for Android. You must also specify
||The extension will run in a Chromium-based browser.|
If no target is specified, the extension will run in
Additional CLI options passed to the Browser binary. Example:
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.
Path to a custom Chromium profile.
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
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
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/**
This option is useful to prevent issues when the number of watched files is higher than what the underlying OS feature allows. As an example, on Linux a
Error: ENOSPC: System limit for number of file watchers reached exception is raised if too many files are being watched (See web-ext#2022).
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.
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.
This specifies the
channel in which the extension is signed. It defaults to
unlisted or the
channel of your extension's latest version. The values for
||The extension gets submitted for public listing on addons.mozilla.org. This type of channel is not well supported and cannot be used for some cases, as documented below.|
||The extension gets submitted for signing for the purpose of self-distribution on your own website.|
--channel=listed for a new extension is not yet supported. See https://github.com/mozilla/web-ext/issues/804
--channel=listed for a new version of a listed extension is not well supported. It will upload your new version to addons.mozilla.org as if you'd submitted it manually. However, the command will fail and you'll have to check addons.mozilla.org/developers/addons for the correct status.
See documentation on the signing API for more information.
Number of milleseconds to wait before giving up on a response from Mozilla's web service. This should always be a number.
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 exisiting extension that you own.
web-ext has the following global options that may apply to multiple commands.
Specifies a particular directory to save artifacts in, e.g. the
.zip file, once you've built an extension. This can be specified as a relative or absolute path, and should always be a string.
If this is not specified, the default is the relative path
Load a config file to set option value defaults. See an example of what config files look like and how they work.
Disable automatic config file discovery.
A list of glob patterns to define which files should be ignored by
lint and other commands. If you specify relative paths, they will be relative to your
Here is an example of ignoring any file within your
--source-dir (or its subdirectories) that ends in the suffix
web-ext build --ignore-files "\*_/_.api-key"
You can specify multiple patterns by separating them with spaces:
web-ext build --ignore-files path/to/first.js path/to/second.js
By default, without the use of
--ignore-files, the following rules are applied:
When you specify custom patterns using
--ignore-files, they are applied in addition to the default patterns.
Order is important! You must specify the web-ext command before specifying the
Lists all the available commands and options available for the web-ext tool.
You can list the options available for a specific command by including the command name as you request help, for example
web-ext --help run.
Disable all features that require standard input.
Specifies the directory of the extension's source code, e.g. when building or running an extension. This can be specified as a relative or absolute path, and should always be a string.
If this is not specified, the default is the directory you are currently inside in your terminal.
Shows verbose output when commands are run.
Shows the version number of the installed web-ext tool.
Environment variables can be set for any option. You:
So, for example, instead of specifying the following source option every time you wish to run the extension:
web-ext run --source-dir=/path/to/my/extension
You could set the source directory as an environment variable like this:
Then you can just specify the run command without options:
A command line option will always override the environment variable. For example, this ignores the environment variable:
web-ext run --source-dir=/another/path/to/source
To define a
false flag option (which does not have a value on the command line), set it to a literal string value of either