fxcss.
Documentation/Command reference
COMMAND REFERENCE

fxcss check

fxcss 0.22.1Source documentation
bash
fxcss check

Runs a compatibility audit and captures the theme in a disposable Firefox profile. It writes a Markdown report, a machine-readable summary.json, logs and screenshots into a fresh run folder under .fxcss/checks/. Without a configuration file, it uses installed Stable, captures all optional stylesheets and fails on actionable selector findings. Visual comparison is enabled when you supply a baseline.

The terminal shows the current phase and each accounted-for view, including views Firefox explicitly does not support, while the full details stay in the run logs. The report links directly to each captured screenshot and distinguishes a check with no visual baseline from one with advisory image changes. When comparing captures, it shows the baseline and current Firefox environments so you can spot version, OS, display-scale or window-size differences. If you interrupt a run, check still writes a report pointing to completed captures; views left unfinished are marked separately from failures. Rerun the command to finish. If interruption occurs during a baseline update, inspect the baseline directory before running another update.

Save settings in .fxcss.json at the theme's root to use the same checks locally and in CI:

json
{
  "firefox": ["stable"],
  "variants": "all",
  "baseline": ".fxcss/baseline",
  "out": ".fxcss/checks",
  "strict": true,
  "strict_vars": false,
  "max_changed_percent": 0.1
}

Create a baseline explicitly, then compare later runs against it:

bash
fxcss check --update-baseline
# Edit the theme, then review the combined report.
fxcss check

--update-baseline accepts new captures only when every configured browser's audit and capture succeed under your settings. It skips comparison with the old baseline during that run. Existing baselines are preserved on a failed check; normal runs never replace them. Review the new captures when accepting a baseline. Existing directories not created by check are not replaced. Every standard view and selected option must be accounted for in capture-coverage.json: captured, explicitly unsupported, or failed. A missing view or failed browser state prevents baseline updates, even on the first run. Baselines made before coverage reports were added must be captured again.

Add installed channels such as "beta" or "nightly" to the browser list; each gets a separate baseline. Missing browsers are reported as errors while the remaining browsers are still checked. Keep baselines for different operating systems separate. --firefox beta overrides the list for one run.

Setting or option Behavior
strict / --strict Fail on actionable selector findings; --no-strict makes them advisory.
strict_vars / --strict-vars Also fail on dead custom properties; deliberate fxcss-keep overrides remain exempt.
max_changed_percent / --max-changed-percent Fail when any view exceeds this percentage, or a new view has no baseline. Set the saved value to null for advisory pixel differences. Missing baseline views always need attention.
variants / --variants Capture all, named stylesheets or combinations such as compact+dark. Set the saved value to null to capture the base theme only.
toolbar / --toolbar Apply a toolbar arrangement to the toolbar capture.
baseline, out Paths relative to the theme root; absolute paths also work. baseline: null runs audits and captures without visual comparison.
--config FILE Read a different JSON settings file. Command-line options override saved values.

Exit codes are 0 for completed checks within the configured policy, 1 for findings, and 2 for interruption or configuration, browser, capture or comparison errors. A configured baseline that is missing is an error, not an unchanged result. Invalid settings fail before Firefox is started.

For a custom GitHub workflow with Firefox and a display already available, run fxcss check and upload .fxcss/checks/ even when the check fails. Keep the baseline available in the checkout or download it before checking; update it explicitly when accepting a theme change. Use --firefox "$FIREFOX_BIN" when a runner installs Firefox outside the usual locations. Add generated check reports to your theme repository's .gitignore if you do not intend to commit them.

Getting startedfxcss shot