web-ext command reference

This page lists all the commands and options available under version 8 of the web-ext command line tool. See the version 7 command reference for documentation of the previous version of the tool.

What's changed in Version 8

Released in May 2024, the main change in version 8 of web-ext is that web-ext sign now creates a listing for an extension not previously listed on addons.mozilla.org (AMO) by default. This feature was previewed in version 7 with the --use-submission-api option, which is now removed. This feature is achieved using the submission features of addons.mozilla.org add-on API v5.

Removed

These version 7 web-ext lint options are removed:

These version 7 web-ext run options are removed:

These version 7 web-ext sign options are removed:

Updates

These web-ext sign options have changed:

  • --amo-base-url no longer requires the (removed) --use-submission-api option to be set.
  • --channel is now required.
  • To submit updates, an extension's manifest.json must include an extension ID.

Additions

These features are added:

Commands

web-ext has these commands; a command's options are included as subsections.

web-ext build

Packages an extension into a .zip file, ignoring files 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.

--as-needed

When you edit and save a source file, rebuild the extension. This enables 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 the destination package file if it exists. Without this option, web-ext exits with an error if the destination file 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

web-ext docs

Opens the web-ext documentation in the user's default browser.

web-ext dump-config

Outputs the tool's configuration settings in JSON format.

web-ext lint

Reports errors in the extension manifest or other source code files. When strict_min_version is set in your extension’s manifest file, lint reports 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 the rules used to validate the extension source.

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

web-ext run

Builds and then temporarily installs an extension on the target application so it can be tested. By default, it watches extension source files and reloads the extension in each target as files change.

--adb-bin

The path to the ADB (Android Device Bridge) executable on the machine you are running web-ext from. By default, the adb executable is 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, ensure yours is set up for development.

Example:

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

Environment variable: $WEB_EXT_ADB_DEVICE

--adb-host

The host name to use when connecting to an Android device with ADB (Android Device Bridge). By default, this is discovered automatically.

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

Forces web-ext to remove any old artifacts discovered at startup. Otherwise, web-ext run provides a warning if it finds old artifacts on the adb device.

Normally, when web-ext exits, it removes all the temporary files written to the target adb device. However, this may not happen, for example, when the device is disconnected before web-ext exits.

Environment variable: $WEB_EXT_ADB_REMOVE_OLD_ARTIFACTS

--browser-console, -bc

Open 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

Open 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.

This option requires Firefox 106 or later.

--firefox, -f

A version of Firefox Desktop to run the extension in. The value is an absolute path to the Firefox executable or an alias string. If not specified, the extension runs in 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:

Alias Firefox executable
firefox The release build of Firefox
beta The beta build of Firefox
nightly The nightly build of Firefox
deved or firefoxdeveloperedition The developer build of Firefox

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 APK name for Firefox on your Android device. If more than one Firefox APK is installed, web-ext shows a list of values to choose from. Otherwise, web-ext uses the available APK.

Example:

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

Environment variable: $WEB_EXT_FIREFOX_APK

--firefox-profile, -p

The base Firefox profile to run the extension in 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 the settings required for web-ext to function are added.

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

Create the profile directory (specified by the --firefox-profile or --chromium-profile options) if it does not exist.

The --firefox-profile option is treated as a directory path when this option is specified.

Environment variable: $WEB_EXT_PROFILE_CREATE_IF_MISSING

--keep-profile-changes

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

This option makes the profile specified by --firefox-profile insecure for daily use. It turns off auto-updates and allows silent remote connections, among other things. Specifically, it makes destructive changes to the profile required for web-ext to operate.

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

Install the extension into the profile before starting the browser. This is a way to support Firefox versions 49 or earlier, 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

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

Here are the supported targets:

Target Application
firefox-desktop The extension runs in Firefox Desktop.
firefox-android The extension runs in Firefox for Android. You must also specify --android-device.
chromium The extension runs in a Chromium-based browser. You can specify a binary with --chromium-binary.

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

Environment variable: $WEB_EXT_TARGET

--args, --arg

Additional CLI options passed to the browser binary. Examples:

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.
If not specified, the default Google Chrome is used.

--chromium-profile

Path to a custom Chromium profile.

--start-url

Open a tab at the specified URL when the browser starts. Example:

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

To open several tabs, declare this option multiple times. 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 watch for changes to specific files without watching the extension directory tree, e.g., the build output 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. Use this to 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 the underlying OS feature allows. For example, on Linux Error: ENOSPC: System limit for number of file watchers reached exception is raised if too many files are being watched (See web-ext#2022).

web-ext sign

This command:

  • creates a listing for your extension on AMO if --channel is set to listed and the extension isn't listed.
  • adds a version to a listed extension if the --channel is set to listed and your extension is listed.
  • downloads a signed copy of the extension if the --channel is set to unlisted.

You must create API access credentials to run this command. Obtain your personal access credentials here.

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

--approval-timeout

Number of milliseconds to wait for approval before giving up. Set to 0 to disable the wait for approval. Defaults to timeout if not set.

Environment variable: $WEB_EXT_API_APPROVAL_TIMEOUT

--amo-base-url

A string containing the add-on submission API base URL. If not specified, defaults to the production API: https://addons.mozilla.org/api/v5/.

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

The channel the extension is signed in. This option is required.

The allowed values for channel are:

Channel Result
listed The extension gets submitted for public listing on addons.mozilla.org.
unlisted The extension gets submitted for signing for self-distribution on your website.

An example of using the --channel option is to create a beta version for an extension listed on addons.mozilla.org.

Environment variable: $WEB_EXT_CHANNEL

--timeout

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

Environment variable: $WEB_EXT_TIMEOUT

--amo-metadata

The path to a JSON file containing an object with metadata for the extension's addons.mozilla.org (AMO) listing.

Metadata is required for the first version of an extension listed on AMO. This metadata can include any of the properties of the addons.mozilla.org add-on API Create request JSON object. However:

  • "categories", "summary" and the version's "license" properties must be provided.
  • Translated fields must include at least one locale.

A minimal JSON file looks like this:

{
  "summary": {
    "en-US": "A short sentence that explains what the extension does."
  },
  "categories": [
    "other"
  ],
  "version": {
    "license": "MPL-2.0"
  }
}

The "license" field accepts one of these SPDX identifiers: MPL-1.1, MPL-2.0, GPL-2.0-or-later, GPL-3.0-or-later, LGPL-2.1-or-later, LGPL-3.0-or-later, MIT, BSD-2-Clause, cc-all-rights-reserved, CC-BY-3.0, CC-BY-NC-3.0, CC-BY-NC-ND-3.0, CC-BY-NC-SA-3.0, CC-BY-ND-3.0, CC-BY-SA-3.0, and all-rights-reserved.

When publishing an extension update metadata isn't required. If metadata isn't provided, the license specified for the first version is reused. However, any of the properties of the addons.mozilla.org add-on API Version Create request JSON object can be provided. For example, if you want to specify "approval_notes", the JSON file looks like this:

{
  "version": {
    "approval_notes": "Information that helps Mozilla reviewers if they review the add-on. Only visible to Mozilla."
  }
}

Environment variable: $WEB_AMO_METADATA

--upload-source-code

The path to an archive file containing human-readable source code for this submission. See Source code submission for details.

Environment variable: $WEB_EXT_API_UPLOAD_SOURCE_CODE

Global options

web-ext has these global options.

--artifacts-dir, -a

The path of a directory to save artifacts in, e.g., the .zip file, when you build 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 ./web-ext-artifacts.

Environment variable: $WEB_EXT_ARTIFACTS_DIR

--config, -c

Load a config file to set option value defaults. See Setting option defaults in a configuration file for more details.

Environment variable: $WEB_EXT_CONFIG

--config-discovery=false, --no-config-discovery

Disable automatic config file discovery.

Environment variable: $WEB_EXT_CONFIG_DISCOVERY=false or $WEB_EXT_NO_CONFIG_DISCOVERY

--ignore-files, -i

A list of glob patterns to define which files should be ignored by build, run, lint, and other commands. If you specify relative paths, they are relative to your --source-dir.

Here is an example that ignores any file within your --source-dir (or its subdirectories) that ends in the suffix .api-key:

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, these rules are applied:

  • Any file ending in .xpi or .zip is ignored
  • Any hidden file (one that starts with a dot) is ignored
  • Any directory named node_modules is ignored

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 --ignore-files option.

Environment variable: $WEB_EXT_IGNORE_FILES

--help, -h

Lists all the commands and options for the web-ext tool. When you request help, you can list the options for a command by including the command name. For example, web-ext --help run.

--no-input

Disable all features that require standard input.

Environment variable: $WEB_EXT_NO_INPUT=true

--source-dir, -s

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 active directory in your terminal.

Environment variable: $WEB_EXT_SOURCE_DIR

--verbose, -v

Shows verbose output when commands are run.

Environment variable: $WEB_EXT_VERBOSE=true

--version

Shows the version number of the installed web-ext tool.

Setting option environment variables

Environment variables can be set for any option. You:

  1. Take the option name.
  2. Remove the two dashes at the start.
  3. Convert the remaining dashes to underscores.
  4. Capitalize the letters.
  5. Prefix the result with $WEB_EXT_.

So, for example, instead of specifying this 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:

WEB_EXT_SOURCE_DIR=/path/to/my/extension

Then you can specify the run command without options:

web-ext run

A command line option always overrides the environment variable. For example, this ignores the environment variable:

web-ext run --source-dir=/another/path/to/source

To define a true / false flag option (which does not have a value on the command line), set it to a literal string value of either true or false. Example:

WEB_EXT_VERBOSE=true