ffrelayctl

A CLI for Firefox Relay written in Go.

Overview

Firefox Relay is a privacy service from Mozilla that provides email and phone number masks to help keep your identity private.

ffrelayctl is a command-line tool for managing Firefox Relay masks directly from the terminal.

Features

• Contact Management: Manage inbound contacts (premium only)
• Email Mask Management: Manage both random and custom domain email masks
• Phone Management: Manage phone masks and forwarding number (premium only)
• Profile Management: View your Relay profile and subscription status
• Data Export: Export your Relay data for backup purposes

Installation

Homebrew (macOS and Linux)

$ brew tap hastefui/tap
$ brew install --cask ffrelayctl

Pre-built Binaries

Download, extract, and install the latest release for your platform from the releases page.

Go Install

ffrelayctl requires Go 1.27 or newer.

$ go install go.hasteful.org/ffrelayctl@latest

Build From Source

Clone this repository, and then:

# Build
$ go build -o ffrelayctl .

# Install
$ go install .

Docker

$ docker build -t ffrelayctl .

Verify Installation

Verify that the installation for ffrelayctl was successful:

$ ffrelayctl --version

Quick Start

Prerequisites

A Firefox Relay account is required.

Authenticating with Firefox Relay

To use ffrelayctl, you need to authenticate with Firefox Relay by providing a Relay API Key, which can be retrieved from the Firefox Relay Settings Page after login.

Verify you're able to retrieve your Relay profile using the API Key for your account:

$ ffrelayctl profiles list --key <replace-me>
# or
$ export FFRELAYCTL_KEY=<replace-me> && ffrelayctl profiles list

Usage

ffrelayctl is A CLI for Firefox Relay.

Usage:
  ffrelayctl [command]

Available Commands:
  help                           # Display help for any command
  contacts list                  # List phone contacts (premium only)
  contacts update                # Update a phone contact (premium only)
  masks list                     # List all masks (filterable)
  masks get                      # Get a mask
  masks create                   # Create a new mask
  masks update                   # Update a mask
  masks delete                   # Delete a mask
  phones list                    # List phone masks (premium only)
  phones discover                # Discover phone masks available (premium only)
  phones search                  # Search phone masks by area code (premium only)
  phones update                  # Update a phone mask (premium only)
  phones forward list            # List forwarding numbers (premium only)
  phones forward get             # Get forwarding number (premium only)
  phones forward register        # Register forwarding number (premium only)
  phones forward verify          # Verify forwarding number (premium only)
  phones forward delete          # Delete forwarding number (premium only)
  profiles list                  # List available Relay profiles
  users list                     # List users for Relay account
  export                         # Export all Firefox Relay account data

Use "ffrelayctl [command] --help" for more information about a command.

Examples

# Fetch the custom domain in use (premium only)
$ ffrelayctl profiles list --output json | jq '.[].subdomain'

# Generate a random mask
$ ffrelayctl masks create --description "GitHub" --generated-for "github.com"

# List all enabled masks
$ ffrelayctl masks list --enabled

# Record what a mask is used on, which normally only the add-on does
$ ffrelayctl masks update 12345 --used-on "github.com"

# List masks recorded as used on a site (case-insensitive substring match)
$ ffrelayctl masks list --used-on github.com

# List random masks generated for a site, disabled and blocking promotional email
$ ffrelayctl masks list --generated-for go.dev --disabled --block-list

# List email addresses in use by all masks
$ ffrelayctl masks list --output json | jq '.[].mask.full_address'

# List all masks containing "newsletter" in the description
$ ffrelayctl masks list --output json | jq '.[] | select(.mask.description | test("newsletter"; "i"))'

# Count total forwarded emails from random masks
$ ffrelayctl masks list --random=true --output json | jq '[.[].num_forwarded] | add'

# Count total masks
$ ffrelayctl masks list --output json | jq '.[].mask.id' | wc -l

# List phone masks
$ ffrelayctl phones list --output json | jq

# List all phone numbers that have texted your Relay number
$ ffrelayctl contacts list --output json | jq '[.[] | select(.last_inbound_type == "text")]'

# Back up an account
$ ffrelayctl export > ffrelay-backup.json
$ ffrelayctl export --include-api-token > ffrelay-full-backup.json

# List all masks using Docker
$ docker run --rm -e FFRELAYCTL_KEY=<replace-me> ffrelayctl profiles list

Library

The Firefox Relay API client is importable without the CLI:

$ go get go.hasteful.org/ffrelayctl/api

package main

import (
	"context"
	"fmt"
	"os"

	"go.hasteful.org/ffrelayctl/api"
)

func main() {
	client := api.NewClient(os.Getenv("FFRELAYCTL_KEY"))

	masks, err := client.ListRelayAddresses(context.Background())
	if err != nil {
		panic(err)
	}

	for _, mask := range masks {
		fmt.Println(mask.FullAddress)
	}
}

See the reference for the full API.

Development

Setup

After cloning this repository, run:

$ make setup

Disclaimer

This is an unofficial CLI not affiliated with or endorsed by Mozilla or Firefox Relay.

License

Licensed under MIT License, see LICENSE for details.

Copyright (c) 2026 hasteful.