Skip to main content

BECK

Send your BIOS files to the right folders on your Recalbox, by matching them against the list of files it says are missing.

CI

What it does

  1. Report: your Recalbox writes a list of the BIOS files it's missing, with the MD5 each one should have.
  2. Scan: BECK works out the MD5 of each file in your BIOS folder.
  3. Match: the name of your file doesn't matter, only its MD5.
  4. Copy: BECK sends each match over the network, under the name and into the folder your Recalbox expects.

BIOS files are copyrighted. BECK doesn't include, download or distribute them: it only matches files you already have. Only use BIOS dumps from hardware you own, and never commit BIOS files to this repository.

Install

BECK is on PyPI as beck-bios. With uv, which also gets the right version of Python for you:

uv tool install beck-bios

Or with pipx, and Python 3.11 or newer:

pipx install beck-bios

Either way, you get a beck command. If your terminal can't find it, run uv tool update-shell or pipx ensurepath, and open a new terminal. Your Recalbox needs to be on your network, with its SMB shares on, as they are on a fresh install.

Quick start

  1. On your Recalbox, generate the report: main menu → BIOS CHECKING → REPORT.

  2. On your computer, create your settings:

    beck config init
    

    They're ready for the usual Recalbox: recalbox.local, with no password. If yours is different, beck config path says where the file is. Change url to use your Recalbox's IP address, as in smb://192.168.1.20/bios, and if it needs a login, set user, and BECK asks for the password.

  3. Put your BIOS files in the folder the settings name:

    mkdir -p ~/beck/bios
    
  4. See what BECK would do. This connects and reads, but changes nothing:

    beck check --dry-run
    
  5. Do it:

    beck check
    
  6. On your Recalbox, scan the BIOS files again, to see the result.

Safety

  • Nothing is deleted unless you ask. BECK copies your files and leaves them where they were. Only --move and --clean-unmatched delete anything, and they ask first. Read what they delete before you use them: --clean-unmatched can delete good files.
  • Nothing on your Recalbox is replaced unless you ask. A file already there is kept and reported, unless you add --overwrite.
  • Your password stays out of files. BECK asks for it, or reads it from BECK_SMB_PASSWORD. It can't go in the settings file.
  • SMB isn't encrypted, so use BECK on a network you trust. The threat model says what BECK protects, and what it doesn't.

Configuration

Flags beat environment variables, which beat the settings file. The guide to the beck command has every setting and every option.

Automation and AI agents

Add --json to any command to get one JSON document on stdout, and branch on the exit code. --json never asks a question. To have an AI agent do this for you, see Using BECK with an agent. For AI agents, AGENTS.md has the rules for using BECK safely.

Troubleshooting

BECK says what went wrong, and its exit code says what kind of problem it is. The troubleshooting guide goes through each message, with why it happens and what to do.

The most common one is that your computer can't find recalbox.local: use your Recalbox's IP address in url instead.

Project status

BECK is in alpha: its first release is out, and later ones may still change how it works. It's been tested on Recalbox 10.1.1 in a virtual machine, but not yet on real hardware. Its automatic tests run on Linux only, so Windows and macOS are untested. The changelog lists what has changed.

If you used an older copy, note that BECK no longer deletes every file it copies, and no longer reads config/config.yml. If you still have that file, BECK prints what to put in the new settings. Delete it afterwards, because it may hold your password in plain text. Older copies tracked it in git, so if you edited it, git pull refuses to update until you move it out of the way.

Contributing

Help is welcome: the contributing guide says how to set up, what to work on, how to send a change, and how to share a report safely.

AGENTS.md has the commands and rules for working on BECK, for people and for AI agents. The roadmap is the plan, and the design explains how it fits together.

Security

To report a problem, see the security policy.

License

GPL-3.0-only. See LICENSE.

Metadata

Release files for beck-bios 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for beck-bios 0.5.0
File Size Uploaded Provenance Actions
beck_bios-0.5.0.tar.gz 57.4 kB With provenance Details for beck_bios-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for beck-bios 0.5.0
File Interpreter ABI Platform Actions
beck_bios-0.5.0-py3-none-any.whl Python 3 none any Details for beck_bios-0.5.0-py3-none-any.whl

Total release size: 122.2 kB

Release files / beck_bios-0.5.0.tar.gz

Download URL beck_bios-0.5.0.tar.gz
Size 57.4 kB
Tags Source
SHA-256 checksum
How to use checksums
6fec9439391d9d141aed7296594817a824f67fb86f0b38ab1521b0c353ead7a9
BLAKE2b-256 checksum
How to use checksums
222a73ed3e761672f64b082fcadecd8bb5b07033494627df8ff9ac61259b0411
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / beck_bios-0.5.0-py3-none-any.whl

Download URL beck_bios-0.5.0-py3-none-any.whl
Size 64.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9ca0685c449cc53f1b94490d9b1e51922a6bcf29e20f632803002d8e17731544
BLAKE2b-256 checksum
How to use checksums
8cc09ce4055d7e77c6b2a343f5f70f2845b31f4255cb98df57b92b2c01c302a8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for beck-bios 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for beck_bios-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page