{"id":14591,"library":"fx-runner","title":"Firefox Runner CLI","description":"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.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"git://github.com/mozilla/node-fx-runner","tags":["javascript","firefox","mozilla","cli"],"install":[{"cmd":"npm install fx-runner","lang":"bash","label":"npm"},{"cmd":"yarn add fx-runner","lang":"bash","label":"yarn"},{"cmd":"pnpm add fx-runner","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[],"quickstart":{"code":"#!/usr/bin/env node\n\nconst { spawn } = require('child_process');\n\n// Example: Start Firefox with a specific profile and additional arguments\nconst firefoxBinary = process.env.FIREFOX_BINARY || '/Applications/Firefox.app/Contents/MacOS/firefox'; // Adjust path for your OS\nconst profilePath = process.env.FIREFOX_PROFILE_PATH || './my-test-profile'; // Path to an existing or new profile\nconst urlToOpen = 'https://www.mozilla.org';\n\nconst args = [\n  'start',\n  '--binary', firefoxBinary,\n  '--profile', profilePath,\n  '--binary-args', `-url ${urlToOpen} -new-window`\n];\n\nconsole.log(`Launching Firefox with: fx-runner ${args.join(' ')}`);\n\nconst child = spawn('fx-runner', args, {\n  stdio: 'inherit', // Pipe child process stdout/stderr to parent\n  shell: true // Use shell to correctly interpret command and args\n});\n\nchild.on('error', (err) => {\n  console.error('Failed to start fx-runner:', err);\n});\n\nchild.on('exit', (code, signal) => {\n  if (code !== 0) {\n    console.error(`fx-runner exited with code ${code} and signal ${signal}`);\n  } else {\n    console.log('fx-runner exited successfully.');\n  }\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.11"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","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.","error":"Error: Command failed: fx-runner start --binary /path/to/firefox-bin ... (or similar 'command not found' for firefox-bin)"},{"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`.","cause":"The `--profile` option expects a path to a Firefox profile directory or a profile name to be provided immediately after it.","error":"fx-runner: error: option '--profile' requires an argument"}],"ecosystem":"npm"}