PhoneToolkit docs

PhoneToolkit is a PyQt6 macOS application distributed as a signed .dmg. Download links appear in your account once you have an active Pro license.

Drag the app into /Applications. First launch will request a license key.

System requirements:

• macOS 13 Ventura or later (arm64 native; Intel build also available)
• USB-A or USB-C port for device connection
• adb, libimobiledevice, idevicerestore, irecovery — the installer prompts to install via Homebrew if missing

On first launch, paste the license key from account → licenses. The app posts the key + a machine UUID to /api/license/verify and receives a signed 14-day session token, cached locally at ~/.phonetoolkit/license.json.

Offline grace: the token stays valid for 14 days from last successful check. After that the app re-verifies on launch; if the server is unreachable, you have a further 14-day window before the app blocks recipes.

Seat limits enforced server-side: Pro tier = 1 machine, Pro Plus = 3 machines. Release a seat from another machine via account → licenses — pick the machine row and click Release.

Drag the AT&T unlock xlsx (filename patterns: *_unlocked_imei_data.xlsx, *_FRM_*_imei_status.xlsx, etc.) onto the import tab. PhoneToolkit reconciles the 15-column schema against carrier_unlock_records and surfaces every device whose status is UNLOCK_NOT_SENT as an orphan.

Orphan queue is shared across all techs on the same license (Pro Plus tier). Assignments persist in SQLite at ~/.phonetoolkit/local.db and sync to KAKEL Cloud every 5 min.

Devices in NETWORK_LOCKED state get the SIM-unlock chain. The chain runs recipes in cost order:

1. nck_service_call (cost 0) — adb shell service call phone 40 i32 0 s16 <NCK>with the matched NCK from carrier_unlock_records. ~10 retry attempts before slot-lock.
2. imei_recheck (cost 5) — re-enumerates IMEI via iphonesubinfo slots 1-20 + getprops, performs SNR-sibling lookup (IMEI positions 9-14) against carrier_unlock_records. Useful when the imported NCK matches an IMEI sibling rather than the exact device.
3. secret_code_manual (cost 20) — Android-version-gated playbook walking the tech through service-mode codes (*#7465625#, *#27663368378#).
4. mark_blocked (cost 100) — last-resort tracker write to sim_unlock_blocked.

Connect the iPhone in Recovery or DFU mode (see the guide) and the iOS recovery tab activates. Chain:

1. pre_check (cost 0) — reads ECID, CPID, board ID, Apple serial, IMEI via irecovery -q + libimobiledevice lockdown. Cross-references ios_blocked.
2. dfu_restore (cost 10) — idevicerestore --erase --latest -y --ecid <ecid>. ~9 min on iPhone 16 Pro Max with a 12 GB IPSW.
3. activation_lock_assert (cost 20) — tech walks the Hello-screen wizard and reports whether iPhone Locked to Owner appeared.
4. kakel_intake_check (cost 25) — searches local + remote KAKEL Store records for prior sale chain (used for AppleCare escalation packets).
5. mark_blocked (cost 100) — persistent record in ios_blocked.

Honesty about hard limits — see the product page for the full list:

• iCloud / Apple Activation Lock bypass — impossible without owner credentials. We detect and document.
• FRP bypass on Android 14+ — impossible without owner credentials.
• Modern Exynos firmware writes via Odin — Samsung-side protocol wall.

License rejects with seats_exhausted: you've hit the per-license activation limit. Open the activations list in your KAKEL account and release a machine you no longer use.

irecovery hangs: the USB endpoint is half-closed from a previous restore. Unplug the iPhone, force-reboot it out of DFU, and reconnect.

SIM unlock returns "exception thrown by serviceCall": NCK retry counter likely exhausted on that device. Move to secret_code_manual or mark blocked.

For anything else: support@kakel.io with the run log from ~/.phonetoolkit/logs/.