restorekit

Reformat an Apple Silicon Mac with one command.

Trigger DFU, detect the target, download the right firmware, and restore. A cross-platform CLI and desktop app for macOS, Linux, and Windows.

restorekit replaces the Apple Configurator dance with a single tool. It puts a cabled Mac into DFU mode, identifies exactly which Mac it is, fetches the matching macOS IPSW, and restores it — start to finish. It runs on macOS, Linux, and Windows, as a command-line tool or a desktop app built on the same engine.

[!WARNING] A restore erases everything on the target Mac. Double-check you have the right device and a backup before running restore or run.

Install

brew install fcjr/fcjr/restorekit-cli   # Homebrew (macOS + Linux)
cargo install restorekit-cli            # from crates.io

Or grab a binary from the releases page. Prefer a GUI? The desktop app wraps the same engine.

Quickstart

Cable the target Mac to your host's DFU port, then:

sudo restorekit run

That's the whole flow: it triggers DFU, waits for the device, downloads the correct firmware (cached for next time), asks you to confirm the erase, and restores. The target reboots into Setup Assistant.

On Linux, you can avoid sudo by installing a udev rule first.

Commands

Handy flags: --os-version 26.5.2 pins a build · --ipsw ./file.ipsw uses a local firmware · --revive keeps user data instead of erasing · --yes skips the confirmation · --json emits newline-delimited JSON events · -v streams the full restore log.

How it works

1. Trigger — On an Apple Silicon Mac host, restorekit sends Apple USB-PD Vendor Defined Messages through the host's Type-C port controller to reboot the target into DFU (a Rust port of macvdmtool). On other hosts it prints the manual key-combo instead.
2. Detect — It scans USB for a Mac in DFU mode and reads the chip and board IDs from the device's serial string to identify the exact model.
3. Fetch — It resolves the correct IPSW from the ipsw.me API (falling back to Apple's own feed), then downloads it — resumable and checksum-verified — into ${XDG_CONFIG_HOME:-~/.config}/restorekit/firmwares.
4. Restore — It drives the statically-linked idevicerestore to restore or revive the device, reporting each step.

DFU port

Use a data-capable USB-C (or Thunderbolt) cable and the target's DFU port:

Platform support

Triggering DFU electronically needs an Apple Silicon Mac host and sudo; everywhere else, put the target into DFU by hand and restorekit takes it from there. On Linux, restorekit embeds its own usbmuxd server — no external daemon needed — but requires USB device access (see Linux USB permissions below). On Windows the target in DFU/recovery needs the WinUSB driver bound to it: run restorekit setup-driver once (the desktop app offers a one-click Set up USB access), and it's installed for every Mac after that. It's a self-signed driver package, so approve the one-time Windows prompt. (Prefer to do it by hand? Zadig or the UsbDk filter work too.)

Linux USB permissions

On Linux, restorekit needs write access to Apple USB devices. You can either run with sudo, or install a udev rule so it works without root:

sudo cp udev/51-restorekit.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

After installing the rule, unplug and re-plug the device (or re-enter DFU) so the new permissions apply. This is a one-time setup — the rule persists across reboots.

The .deb package installs this rule automatically. For the .AppImage or a cargo install build, copy it manually as shown above.

Desktop app

A cross-platform app (Tauri + Svelte) wraps the same engine for a point-and-click restore: detect the device, download, confirm, restore — with live progress. It links the restorekit library directly, so it's the same code path as the CLI.

brew install --cask restorekit          # macOS

On Linux, grab the .deb or .AppImage, and on Windows the installer, from the releases page. One-click Enter DFU needs an Apple Silicon Mac host; on other hosts the app shows the manual key-combo and takes over once the target is in DFU.

See docs/gui-prd.md for the app's design.

As a library

The CLI is a thin shell over the restorekit crate, which exposes the whole workflow with no I/O of its own — every operation reports progress through a callback, so you can build a GUI on the same engine.

use restorekit::{dfu, firmware};
use std::time::Duration;

let device = dfu::wait_for_dfu(Duration::from_secs(60))?;
let fw = firmware::resolve(device.identifier().unwrap(), None)?;
let cache = firmware::default_cache_dir()?;
let ipsw = firmware::download(&cache, &fw, &mut |event| {
    // render progress however you like
})?;

See the API docs for the full surface.

Building from source

git clone --recurse-submodules https://github.com/fcjr/restorekit
cd restorekit
cargo build --release

The build compiles the full idevicerestore C stack from pinned submodules, so the first build takes a few minutes. On Linux, install the toolchain first:

sudo apt-get install -y \
  build-essential autoconf automake libtool pkg-config cmake autoconf-archive \
  libusb-1.0-0-dev libssl-dev libcurl4-openssl-dev zlib1g-dev

Those -dev packages only satisfy the vendored libraries' configure checks — OpenSSL, libcurl, and zlib are still linked statically, so the finished binary depends only on libc and libusb.

Windows

The C stack is built with autotools, which needs the GNU toolchain, so Windows builds target x86_64-pc-windows-gnu from an MSYS2 MINGW64 shell. In that shell:

pacman -S --needed base-devel git make autoconf automake libtool \
  autoconf-archive gettext-devel pkgconf perl \
  mingw-w64-x86_64-gcc mingw-w64-x86_64-pkgconf mingw-w64-x86_64-cmake \
  mingw-w64-x86_64-libusb mingw-w64-x86_64-nasm
rustup default stable-x86_64-pc-windows-gnu   # GNU host toolchain
rustup target add x86_64-pc-windows-gnu

Then, with the Windows cargo on PATH, build from the repo root:

cargo build --release -p restorekit-cli --target x86_64-pc-windows-gnu

The -gnu host toolchain matters: build scripts link with ld instead of MSVC's link.exe, which MSYS2's coreutils link would otherwise shadow. As on Linux, OpenSSL/libcurl/zlib link statically; the binary needs only libusb.

Releasing

Releases are automated: bump the version, push a v* tag, and CI publishes the GitHub Release, the Homebrew cask, and the crates. See docs/DEPLOYMENT.md.

License

Apache-2.0 — see LICENSE and NOTICE. The DFU-trigger code is a Rust port of macvdmtool (also Apache-2.0); the vendored C libraries keep their own licenses.