ffcv

Firefox Configuration Viewer - Parse and query Firefox preference files with ease.

ffcv is both a command-line tool and a Rust library for working with Firefox's prefs.js configuration files. It provides a structured way to parse, query, and understand Firefox settings across all platforms (Linux, macOS, Windows).

Features

Complete Parsing - Handles all Firefox preference types:
- User preferences (user_pref)
- Default preferences (pref)
- Locked preferences (lock_pref)
- Sticky preferences (sticky_pref)
Firefox Default Preferences - Extract and merge Firefox's built-in default preferences from omni.ja:
- Built-in defaults from omni.ja archives
- Global defaults from greprefs.js
- User preferences from prefs.js
- Proper precedence handling (built-ins < globals < user)
- Source tracking for each preference
Firefox Installation Discovery - Automatic Firefox installation detection:
- Cross-platform support (Linux, macOS, Windows)
- Multiple Firefox version support (ESR, Release, Beta)
- Version detection from application.ini
Powerful Querying - Filter preferences using glob patterns like "network.*" or "browser.*.enabled"
Cross-Platform - Automatic Firefox profile discovery on Linux, macOS, and Windows
Rich Data Types - Supports boolean, integer, float, string, and null values
Type-Safe API - Convenience trait for easy value type checking and extraction
Simple Interface - All public types and functions available at crate root
Human-Readable Explanations - Optional explanations for what preferences do
Flexible Output - JSON output with customizable formatting
Well-Tested - Comprehensive test coverage with robust error handling

Installation

Command-Line Tool

Install via cargo:

cargo install ffcv

This installs the ffcv binary for viewing Firefox configurations from your terminal.

Library Usage

Add to your Cargo.toml:

[dependencies]
ffcv = "1.1.0"

Command-Line Usage

List Firefox Profiles

# List all Firefox profiles on your system
ffcv profile

# Specify a custom Firefox profiles directory
ffcv profile --profiles-dir /custom/path

List Firefox Installations

# List detected Firefox installations
ffcv install

# List all Firefox installations (including multiple versions)
ffcv install --all

# Show detailed information about each installation
ffcv install --all --verbose

View Configuration

# View all preferences (includes Firefox defaults by default)
ffcv config

# View preferences for a specific profile
ffcv config --profile myprofile

# Query specific preferences by glob pattern
ffcv config --query "network.*"
ffcv config --query "browser.*" --query "extensions.*"

# Get a single preference (raw output)
ffcv config --get "network.proxy.type"

# View all preferences including built-in defaults
ffcv config --all

# View only user-modified preferences (default behavior)
ffcv config

# Specify custom Firefox installation directory
ffcv config --install-dir /usr/lib/firefox

# Read from stdin
cat prefs.js | ffcv config --stdin

# Output as JSON (includes source information)
ffcv config --output-type json-array

# Output as simple JSON object (no source information)
ffcv config --output-type json-object

Library Usage

Basic Parsing

use ffcv::parse_prefs_js;
use std::fs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let content = fs::read_to_string("prefs.js")?;
    let entries = parse_prefs_js(&content)?;

    for entry in entries {
        println!("{:?} = {:?}", entry.key, entry.value);
    }

    Ok(())
}

Query Preferences

use ffcv::{parse_prefs_js, query_preferences};
use std::fs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let content = fs::read_to_string("prefs.js")?;
    let entries = parse_prefs_js(&content)?;

    // Query network-related preferences
    let network_prefs = query_preferences(&entries, &["network.*"])?;

    // Display matching entries
    for entry in network_prefs {
        println!("{} = {:?}", entry.key, entry.value);
    }

    Ok(())
}

Profile Discovery

use ffcv::list_profiles;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let profiles = list_profiles(None)?;

    for profile in profiles {
        println!("Profile: {}", profile.name);
        println!("  Path: {}", profile.path.display());
        println!("  Default: {}", profile.is_default);
    }

    Ok(())
}

Firefox Installation Discovery

use ffcv::find_firefox_installation;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    if let Some(installation) = find_firefox_installation()? {
        println!("Firefox found at: {}", installation.path.display());
        println!("Version: {}", installation.version);
        println!("Has omni.ja: {}", installation.has_omni_ja);
        println!("Has greprefs.js: {}", installation.has_greprefs);
    } else {
        println!("No Firefox installation found");
    }

    Ok(())
}

Merge All Preferences

use ffcv::{merge_all_preferences, MergeConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = MergeConfig {
        include_builtins: true,   // Include omni.ja defaults
        include_globals: true,    // Include greprefs.js
        include_user: true,       // Include user prefs.js
        continue_on_error: true,  // Don't fail if some sources are missing
    };

    let merged = merge_all_preferences(
        &profile_path,
        None,  // Auto-detect Firefox installation
        &config
    )?;

    println!("Loaded {} preferences", merged.entries.len());
    println!("Sources: {:?}", merged.loaded_sources);

    if !merged.warnings.is_empty() {
        println!("Warnings:");
        for warning in &merged.warnings {
            println!("  - {}", warning);
        }
    }

    Ok(())
}

Working with Preference Values

use ffcv::{PrefEntry, PrefValue, PrefValueExt};

fn process_entry(entry: PrefEntry) {
    // Use convenience methods from PrefValueExt trait
    if let Some(enabled) = entry.value.as_bool() {
        if enabled {
            println!("{} is enabled", entry.key);
        } else {
            println!("{} is disabled", entry.key);
        }
    } else if let Some(n) = entry.value.as_int() {
        println!("{} = {} (integer)", entry.key, n);
    } else if let Some(s) = entry.value.as_string() {
        println!("{} = \"{}\"", entry.key, s);
    } else {
        println!("{} = {:?}", entry.key, entry.value);
    }
}

Finding a Specific Profile

use ffcv::find_profile_path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Find a specific Firefox profile by name
    let profile_path = find_profile_path("default", None)?;

    println!("Profile path: {}", profile_path.display());

    Ok(())
}

API Design

ffcv provides a clean, simplified API with all public types and functions available at the crate root:

Core Types:

PrefEntry - A single preference entry with key, value, type, and source
PrefType - The type of preference (User, Default, Locked, Sticky)
PrefValue - The value of a preference (Bool, Int, Float, String, Null)
PrefValueExt - Convenience trait for type-safe value access
PrefSource - Where a preference came from (BuiltIn, GlobalDefault, User, SystemPolicy)
FirefoxInstallation - Metadata about a Firefox installation
MergedPreferences - Combined preferences from multiple sources

Core Functions:

parse_prefs_js() - Parse preference file contents
parse_prefs_js_file() - Parse directly from a file path
query_preferences() - Filter preferences by glob patterns
merge_all_preferences() - Merge preferences from all sources
list_profiles() - List all Firefox profiles
find_profile_path() - Find a specific profile by name
find_firefox_installation() - Auto-detect Firefox installation
get_prefs_path() - Get the prefs.js path for a profile

All functions return Result<T, Error> for proper error handling.

Preference Types

Firefox uses several types of preferences:

User Preferences (user_pref) - Set by the user
Default Preferences (pref) - Application defaults
Locked Preferences (lock_pref) - Administratively locked, cannot be changed
Sticky Preferences (sticky_pref) - User preferences that persist across updates

Each preference has a value type:

Boolean (true/false)
Integer (64-bit)
Float (64-bit)
String (including JSON-encoded data)
Null

Environment Variables

ffcv respects the following environment variables for Firefox profile discovery:

FIREFOX_BIN - Path to Firefox binary
MOZ_PROFILES_DIR - Custom Firefox profiles directory
PROGRAMFILES - Windows Program Files directory (for Firefox detection)
HOME - User home directory (Unix-like systems)
APPDATA - Application Data directory (Windows)

Documentation

Full API documentation is available on docs.rs.

To build and view the documentation locally:

cargo doc --open

Platform Support

ffcv is tested and supported on:

Linux (x86_64, ARM64)
macOS (x86_64, ARM64/Apple Silicon)
Windows (x86_64)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is dual-licensed under either:

MIT License (LICENSE-MIT.txt or http://opensource.org/licenses/MIT)
Apache License, Version 2.0 (LICENSE-APACHE-2.0.txt or http://www.apache.org/licenses/LICENSE-2.0)

You may choose either license for your use.

Version 1.0

ffcv provides a stable and well-tested API. The library offers a clean, simplified interface with comprehensive Firefox preference parsing capabilities. All public types and functions are available at the crate root for easy importing.

Acknowledgments

Built for the Rust community to make Firefox configuration management easier and more programmatic.

Inspired by the need for better tools to understand and manage Firefox's extensive preference system.

ffcv 1.1.0

ffcv

Features

Installation

Command-Line Tool

Library Usage

Command-Line Usage

List Firefox Profiles

List Firefox Installations

View Configuration

Library Usage

Basic Parsing

Query Preferences

Profile Discovery

Firefox Installation Discovery

Merge All Preferences

Working with Preference Values

Finding a Specific Profile

API Design

Preference Types

Environment Variables

Documentation

Platform Support

Contributing

License

Version 1.0

Acknowledgments