This page covers the browser command system used by uBlock Origin (MV2): how commands are declared in manifests, how commands.js handles them at runtime, and what each command does. This is separate from the UI interactions documented in the popup (7.1) and dashboard (7.2), and from the vAPI browser abstraction layer (8.2) through which the command API is accessed. Thunderbird is not covered here, as it has no commands section in its manifest.
The browser commands API lets extensions register named actions that users can bind to keyboard shortcuts via the browser's extension management UI. uBlock Origin declares seven commands in each supported manifest (Chromium, Firefox, Opera). The background script src/js/commands.js listens for these commands and dispatches them to the appropriate subsystems.
No default key bindings are assigned in the manifests — all shortcut bindings must be configured by the user through the browser's own keyboard shortcut settings page.
Each platform manifest declares the same set of commands. The description values are i18n message references that the browser displays in its shortcut settings UI.
Declared commands — all supported platforms:
| Command ID | i18n Description Key | Chromium | Firefox | Opera |
|---|---|---|---|---|
launch-element-zapper | __MSG_popupTipZapper__ | ✓ | ✓ | ✓ |
launch-element-picker | __MSG_popupTipPicker__ | ✓ | ✓ | ✓ |
launch-logger | __MSG_popupTipLog__ | ✓ | ✓ | ✓ |
open-dashboard | __MSG_popupTipDashboard__ | ✓ | ✓ | ✓ |
relax-blocking-mode | __MSG_relaxBlockingMode__ | ✓ | ✓ | ✓ |
toggle-cosmetic-filtering | __MSG_toggleCosmeticFiltering__ | ✓ | ✓ | ✓ |
toggle-javascript | __MSG_toggleJavascript__ | ✓ | ✓ | ✓ |
_execute_browser_action | (built-in) | — | ✓ | — |
Firefox additionally registers the _execute_browser_action special command platform/firefox/manifest.json30-31 which is a browser-reserved command name that opens the extension popup. Thunderbird's manifest platform/thunderbird/manifest.json1-94 has no commands key at all.
Sources: platform/chromium/manifest.json15-37 platform/firefox/manifest.json29-53 platform/opera/manifest.json15-37
commands.jsAll command handling is implemented in src/js/commands.js. The module is an IIFE that registers a single listener on vAPI.commands.onCommand.
Guard clause: The module exits immediately if vAPI.commands is not an object src/js/commands.js32 so on platforms that do not provide the commands API (e.g., Thunderbird), this module is a no-op.
Diagram: Command Dispatch Flow
Sources: src/js/commands.js122-180
open-dashboardOpens dashboard.html in a new tab (or selects it if already open). This is the only generic command — it does not require a current tab and runs before the vAPI.tabs.getCurrent() call src/js/commands.js124-131
launch-element-pickerChecks µb.userFiltersAreEnabled() src/js/commands.js138 before proceeding. If user filters are disabled, the command does nothing. If enabled, it falls through to the same execution path as launch-element-zapper, calling µb.elementPickerExec with the isZapper flag set to false.
launch-element-zapperCalls µb.elementPickerExec(tab.id, 0, undefined, true) src/js/commands.js142-148 Sets µb.epickerArgs.mouse = false so the picker does not use mouse coordinates. The true argument activates zapper mode rather than picker mode.
launch-loggerOpens logger-ui.html. If the current tab is not an internal extension page, the hash #_+{tab.id} is appended src/js/commands.js151-159 which causes the logger UI to pre-filter its output to that specific tab. For more on the logger, see 7.3.
toggle-cosmetic-filteringCalls µb.toggleHostnameSwitch with name: 'no-cosmetic-filtering' for the current page's hostname src/js/commands.js164-168 This toggles the per-site cosmetic filtering switch without reloading the page. For the cosmetic filtering system, see 5.2.
toggle-javascriptCalls µb.toggleHostnameSwitch with name: 'no-scripting' for the current hostname, then immediately reloads the tab via vAPI.tabs.reload src/js/commands.js170-176 A page reload is required because existing scripts already executed cannot be un-executed.
relax-blocking-modeThis command steps the current tab's hostname through a sequence of progressively less restrictive blocking profiles. The logic is encapsulated in the relaxBlockingMode closure src/js/commands.js34-120
relaxBlockingMode — Detailed BehaviorDiagram: relaxBlockingMode State Machine
Profile bitmask reference:
| Bit (decimal) | Binary | Meaning |
|---|---|---|
| 1 | 0b00000001 | Reload page when this profile is applied |
| 2 | 0b00000010 | no-scripting switch is active |
| 4 | 0b00000100 | 3rd-party requests blocked (firewall rule) |
| 8 | 0b00001000 | 3rd-party scripts blocked (firewall rule) |
| 16 | 0b00010000 | 3rd-party frames blocked (firewall rule) |
The reloadTimers map src/js/commands.js35 holds vAPI.defer timer handles keyed by tab ID. This coalesces rapid repeated invocations of the command into a single reload after a 547 ms debounce. Firewall rule changes only apply when µb.userSettings.advancedUserEnabled is true src/js/commands.js69
Sources: src/js/commands.js34-120
Diagram: commands.js Dependencies
Sources: src/js/commands.js22-24 src/js/commands.js122-180
| Feature | Chromium | Firefox | Opera | Thunderbird |
|---|---|---|---|---|
| Commands declared in manifest | ✓ | ✓ | ✓ | — |
commands.js listener active | ✓ | ✓ | ✓ | — (no-op) |
_execute_browser_action | — | ✓ | — | — |
| Default key bindings in manifest | — | — | — | — |
| User-configurable shortcuts | ✓ | ✓ | ✓ | — |
Sources: platform/chromium/manifest.json15-37 platform/firefox/manifest.json29-53 platform/opera/manifest.json15-37 platform/thunderbird/manifest.json1-94 src/js/commands.js32
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.