Firefox Runner CLI

1.4.0 · active · verified Sun Apr 19

fx-runner is a Node.js command-line interface (CLI) tool developed by Mozilla, designed to control and interact with Firefox browsers programmatically from the terminal. It simplifies tasks such as launching Firefox with specific profiles, passing arguments directly to the browser binary, and managing browser instances for testing or automation purposes. The project is actively maintained, with the latest stable version being 1.4.0, released in January 2024. Releases appear to be ad-hoc, driven by bug fixes and minor feature additions rather than a fixed cadence. Unlike full-fledged browser automation libraries (like Puppeteer or Playwright), `fx-runner` focuses purely on direct CLI interaction, making it particularly suitable for scripting environments, shell-based workflows, and scenarios where a lightweight, non-programmatic JavaScript control is preferred. Its primary differentiator is this direct command-line control over the Firefox binary and its associated profiles.

Common errors

```
Error: Command failed: fx-runner start --binary /path/to/firefox-bin ... (or similar 'command not found' for firefox-bin)
```
cause After version 1.4.0, `fx-runner` internally switched from using `firefox-bin` to `firefox`. If your environment or specific Firefox installation only exposed `firefox-bin` or if `firefox` is not in your PATH, the command may fail.

fix Upgrade `fx-runner` to the latest version. If using a custom Firefox installation, verify that the `firefox` executable is available or explicitly specify its path using the `--binary` option, e.g., `fx-runner start --binary /Applications/Firefox.app/Contents/MacOS/firefox`.
```
fx-runner: error: option '--profile' requires an argument
```
cause The `--profile` option expects a path to a Firefox profile directory or a profile name to be provided immediately after it.

fix Ensure you provide a valid path or profile name. Example: `fx-runner start --profile /path/to/my/profile` or `fx-runner start --profile default`.

Warnings

breaking Starting with version 1.4.0, `fx-runner` changed its internal usage from `firefox-bin` to `firefox` as the default binary name. While this was a fix, users with highly customized Firefox installations or environments that explicitly relied on `firefox-bin` might experience launch failures.
Fix: Ensure that the `firefox` executable is correctly located in your system's PATH or explicitly specify the full path to the `firefox` binary using the `--binary <path>` option.
gotcha Versions prior to 1.0.11 had known vulnerabilities related to the `lodash` dependency, which could pose security risks. While `fx-runner` itself updated `lodash` in patch releases (1.0.9, 1.0.10, 1.0.11), using older versions might expose projects to these issues.
Fix: Upgrade to `fx-runner` version 1.0.11 or newer to ensure that `lodash` vulnerabilities (specifically those addressed in lodash versions >=4.17.10) are mitigated.
gotcha On Windows and macOS, earlier versions had issues correctly locating installed Firefox binaries and profiles. Specifically, 1.1.0 fixed Windows registry lookups, and 1.0.13 fixed macOS Developer Edition lookup and Beta/Nightly paths. Users on these platforms might encounter issues with `fx-runner` failing to find Firefox if using older versions.
Fix: Update to at least `fx-runner` version 1.1.0 (for Windows fixes) or 1.0.13 (for macOS fixes) to benefit from improved Firefox discovery logic. If issues persist, explicitly provide the Firefox binary path and profile path using `--binary` and `--profile` options.

Install

npm install fx-runner npm
yarn add fx-runner yarn
pnpm add fx-runner pnpm

Quickstart

Demonstrates how to execute the `fx-runner` CLI using Node.js's `child_process.spawn` to launch Firefox with a custom profile and a specific URL.

#!/usr/bin/env node

const { spawn } = require('child_process');

// Example: Start Firefox with a specific profile and additional arguments
const firefoxBinary = process.env.FIREFOX_BINARY || '/Applications/Firefox.app/Contents/MacOS/firefox'; // Adjust path for your OS
const profilePath = process.env.FIREFOX_PROFILE_PATH || './my-test-profile'; // Path to an existing or new profile
const urlToOpen = 'https://www.mozilla.org';

const args = [
  'start',
  '--binary', firefoxBinary,
  '--profile', profilePath,
  '--binary-args', `-url ${urlToOpen} -new-window`
];

console.log(`Launching Firefox with: fx-runner ${args.join(' ')}`);

const child = spawn('fx-runner', args, {
  stdio: 'inherit', // Pipe child process stdout/stderr to parent
  shell: true // Use shell to correctly interpret command and args
});

child.on('error', (err) => {
  console.error('Failed to start fx-runner:', err);
});

child.on('exit', (code, signal) => {
  if (code !== 0) {
    console.error(`fx-runner exited with code ${code} and signal ${signal}`);
  } else {
    console.log('fx-runner exited successfully.');
  }
});

view raw JSON →