Skip to content

5. Control CLI

Jump to bottom
Andrea ZGuz edited this page Oct 9, 2026 · 2 revisions

What is the Control CLI?

A click/rich command-line tool for BomberCat firmwares. It talks to a BomberCat over USB-serial to configure it, start/stop the NFCGate relay, watch it live, capture the relayed APDUs to Wireshark; on the DetectTags firmware — read NFC tags directly with the board's PN7150; on MifareClassic — authenticate, read, write, dump and restore Mifare Classic cards; on DetectReaders — detect the readers/terminals that probe it; and on magspoof — control magstripe emulation: play/inspect the active card, manage a flash-resident multi-card store, and emulate/read EMV cards over NFC; and on EMVyBomberCat — read EMV cards, tunnel raw APDUs to a live card, and emulate tags/magstripe/NDEF/EMV cards while watching each APDU live.

Control plane only. No APDUs travel over serial — those go over WiFi/TCP to the nfcgate-server. The USB link is a text, line-based control channel: it configures, arms, starts, monitors and captures the device, nothing more (docs/NFCGATE_PLAN.md Fase 6). Keep this in mind everywhere below — see the architecture diagram for how the pieces connect.

Note

This tool is still under development. Some commands may be missing at this point to test all the firmwares. We kindly invite you to keep posted on the Control CLI Tool and firmware updates.

Control CLI installation

Windows

Important

The BomberCat installer requires administrator rights to install on your system.

  • System requirements:
    • Windows 10 or 11, 64-bit
    • Administrator rights
    • At least 150 MB of free disk space

1.Download the installer bombercat-x.x.x.x.exe from the releases section of the bombercat-tools repository.

2.Run the installer and follow the installation wizard. Two options are worth reviewing on the Select Additional Tasks page:

  • Add bombercat to the system PATH — checked by default, and needed to run bombercat from any terminal. Leave it on.
  • Create a Desktop icon — unchecked by default; the CLI is meant to be run from a terminal, so the shortcut only opens a console window.

Note

You may be prompted with a window indicating that Microsoft Defender SmartScreen prevented the installation — the installer is unsigned (no Authenticode certificate yet). To bypass this prompt, click on More info and then on the Run anyway button.

3.Complete the installation by clicking the Finish button to exit the installer.

4.Open a new terminal (PowerShell or cmd) — the PATH change only applies to sessions started after the install — and verify:

bombercat --version
bombercat device list

macOS

  • System requirements:
    • macOS 13 (Ventura) or newer — the packages are built on GitHub's macOS runners, older releases are untested
    • Intel or Apple Silicon (M1, M2, M3, M4) Mac
    • At least 150 MB of free disk space

You need to first verify the architecture of your Mac with the command:

uname -m

The command will return any of the following, depending on the Mac architecture:

Once you know your architecture, continue with the instructions according to your variant. There is no universal build — installing the wrong one gives you a binary that will not run.

Intel Macs (x86_64)

1.Download the installer bombercat-x.x.x.x-x86_64.pkg from the releases section of the bombercat-tools repository.

2.Open a new terminal session in the path where the installer is located.

3.Run the command:

sudo installer -allowUntrusted -pkg bombercat-x.x.x.x-x86_64.pkg -target /

Replace the BomberCat name to match the actual name of the installer file.

Apple Silicon Macs (Apple M processors)

1.Download the installer bombercat-x.x.x.x-arm64.pkg from the releases section of the bombercat-tools repository.

2.Open a new terminal session in the path where the installer is located.

3.Run the command:

sudo installer -allowUntrusted -pkg bombercat-x.x.x.x-arm64.pkg -target /

Replace the BomberCat name to match the actual name of the installer file.

Note

The package is unsigned and not notarized (no Apple Developer ID yet). If Gatekeeper refuses the file because it was downloaded with a browser, strip the quarantine flag first and install again:

xattr -d com.apple.quarantine bombercat-x.x.x.x-arm64.pkg

Post-installation (macOS)

1.Verify the installation:

bombercat --version
bombercat device list

2.Nothing else is required: macOS exposes the board as /dev/cu.usbmodem* with no group membership or udev rules involved — setup-env is a Linux-only command and is not registered here. Optionally install shell completion.

Linux

Debian/Ubuntu (.deb)

  • System requirements:
    • Debian 12+ or Ubuntu 22.04+ (needs python3 ≥ 3.12)
    • sudo privileges
    • At least 100 MB of free disk space

1.Download the installer bombercat-x.x.x.x.deb from the releases section of the bombercat-tools repository.

2.Open a new Terminal session in the installer file location.

3.Run the command:

sudo apt install ./bombercat-x.x.x.x.deb

Replace the BomberCat name to match the actual name of the installer file.

apt pulls the recommended udisks2, which bombercat flash uses to auto-mount the board's RPI-RP2 bootloader drive. If you install with sudo dpkg -i instead, recommendations are skipped, so install the dependencies afterwards:

sudo apt-get install -f
sudo apt install udisks2

Note

You can verify BomberCat is installed by running the command:

bombercat --version

The package only depends on python3: click, rich, pyserial and the rest are vendored inside it, so there is no venv to manage and no risk of clashing with your system Python packages.

Arch Linux (.pkg.tar.zst)

  • System requirements:
    • Arch Linux (or derivatives like Manjaro)
    • sudo privileges
    • python ≥ 3.12 (the package is built against the current Arch Python)

1.Download the latest version of the installer package.

URL=(curl-shttps://api.github.com/repos/ElectronicCats/bombercat-tools/releases/latest|grep"browserdownloadurl.*pkg.tar.zst"|cut-d'"'-f4)&&wget"URL"

2.Install the package by running the command.

sudo pacman -U bombercat-x.x.x.x.pkg.tar.zst

Replace the BomberCat name to match the actual name of the installer file.

3.Optionally install udisks2, listed as an optional dependency, so flash can auto-mount the bootloader drive:

sudo pacman -S udisks2

Note

You can verify BomberCat is installed by running the command:

bombercat --version

There is no AUR package yet; the .pkg.tar.zst from the releases page is the supported route.

Install from source (all Linux distributions, macOS, Windows)

Needs Python 3.12 or newer.

1.Clone the repository.

git clone https://github.com/ElectronicCats/bombercat-tools.git

2.Navigate to the repository folder.

cd bombercat-tools

3.Create and activate a virtual environment (recommended).

python3 -m venv .venv
source .venv/bin/activate     # On Windows: .venv\Scripts\activate

4.Install the package (this pulls the dependencies from requirements.txt).

python3 -m pip install .
bombercat --version

To hack on the code instead, install the dependencies only and run the script in place:

python3 -m pip install -r requirements.txt
python3 bombercat.py --help

In that mode the command is python3 bombercat.py … unless you set up the bombercat alias. The dev-only commands proto and testserver are available from a source checkout, and hidden from --help in every packaged build.

Extra functions

Shell completion (macOS and Linux systems)

Install tab completion for your shell.

1.Run the following command.

bombercat completion install

Note

If you are using a specific shell, you can specify it explicitly, e.g.:

bombercat completion install --shell bash
bombercat completion install --shell zsh
bombercat completion install --shell fish

2.Restart your shell.

Besides commands and options, this completes firmware names for flash. See completion for the exact files it writes.

Uninstallation instructions

Windows

1.Go to Settings → Apps → Installed Apps → BomberCat.

2.Click on the 3-dot button on the right side and click on Uninstall.

Or run unins000.exe from C:\Program Files\BomberCat\.

The uninstaller removes the PATH entry and the shortcuts it created.

macOS

1.Remove the package receipt.

sudo pkgutil --forget com.electroniccats.bombercat

2.Delete the installed files.

sudo rm -rf /usr/local/opt/bombercat
sudo rm -f /usr/local/bin/bombercat

Linux

1.Run the command in the Terminal:

  • Debian/Ubuntu:

    sudo apt remove bombercat

  • Arch Linux:

    sudo pacman -R bombercat

2.Both remove the packaged udev rules in /lib/udev/rules.d/. The copy setup-env writes lives elsewhere and is left behind on purpose — delete it if you are done with the board:

sudo rm -f /etc/udev/rules.d/99-bombercat.rules
sudo udevadm control --reload-rules

From source / pip 

python3 -m pip uninstall bombercat     # or: make uninstall

Leftover user files (every platform)

Uninstalling never touches your own files. Remove them by hand if you want a clean slate:

  • ~/.bombercat/firmware/ — cached UF2 images downloaded by flash
  • Completion scripts written by completion install: ~/.local/share/bash-completion/completions/bombercat, ~/.zfunc/_bombercat (plus its fpath line in ~/.zshrc), or ~/.config/fish/completions/bombercat.fish

Thank you for reading our Wiki!

Clone this wiki locally