web-ext command reference

This page lists all the commands and options available under the web-ext command line tool.

Commands

web-ext has the following commands available; options specific to these commands are included as subsections.

web-ext build

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 WebExtension manifest.

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

web-ext lint

Reports errors in the WebExtension manifest or other source code files. See the addons-linter project for more information about what kind of rules are used to validate 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

web-ext run

Builds and then temporarily installs an extension on Firefox so it can be tested. By default, this will also watch all extension source files and reload the extension in Firefox as files change.

--firefox

Allows you to specify a particular version of Firefox to run the WebExtension in. This is specified as an absolute path to firefox-bin and should always be a string. If this is not specified, it will attempt to run the extension inside the default installation of Firefox on the system.

Environment variable: $WEB_EXT_FIREFOX

--firefox-profile, -p

Allows you to specify a base Firefox profile to run the WebExtension 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 will run the extension using a new temporary profile.

Environment variable: $WEB_EXT_FIREFOX_PROFILE

--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 since they do not support remote installation. Specifying this option implies --no-reload.

Environment variable: $WEB_EXT_PRE_INSTALL=true

web-ext sign

Packages an extension and signs it so it can be self-hosted. This will create a signed .xpi file instead of a .zip file. You will need to create API access credentials to run this command.

--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/v3 which is the production API.

Environment variable: $WEB_EXT_API_URL_PREFIX

--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 exisiting extension that you own.

Environment variable: $WEB_EXT_ID

Global options

web-ext has the following global options that may apply to multiple commands.

--artifacts-dir, -a

Specifies a particular directory to save artifacts in, e.g the .zip file, once you've built a WebExtension. This can be specified as a relative or absolute path, and should always be a string.

Environment variable: $WEB_EXT_ARTIFACTS_DIR

--help, -h

Lists all the available commands and options available for the web-ext tool.

--source-dir, -s

Specifies the directory of the WebExtension's source code, e.g. when building or running a WebExtension. This can be specified as a relative or absolute path, and should always be a string.

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

WEB_EXT_SOURCE_DIR=/path/to/my/extension

Then you can just specify the run command without options:

web-ext run

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

See also

• web-ext repo
• Getting started with web-ext