tyutool

English | 简体中文

Firmware flash tool for Tuya-class IoT devices. Available as a cross-platform desktop GUI (Tauri 2 + Vue 3) and a standalone CLI binary.

Supported Chips

Family	Chips
Tuya	T1, T2, T3, T5AI
Beken	BK7231N
Espressif	ESP32, ESP32-C3, ESP32-C6, ESP32-S3

Download

Grab the latest release from GitHub Releases. In mainland China, fetch the latest release.json from the Tuya OSS mirror and download from each entry's url (see Update Manifests).

GUI

Platform	Package
Linux x86_64	.AppImage, .deb, .rpm, portable tar.gz
Linux aarch64	.AppImage, .deb, portable tar.gz
macOS (Universal)	.dmg, portable tar.gz
Windows x86_64	NSIS installer (.exe), portable .zip

Recommended downloads by platform (x.x.x = version number — get the latest from Releases)

Platform	Recommended file	Auto-update	Notes
Windows x86_64	★ tyutool-gui_windows_x86_64_nsis_x.x.x.exe	✅	NSIS installer
Windows x86_64	tyutool-gui_windows_x86_64_portable_x.x.x.zip	❌	No-install portable
macOS Universal	★ tyutool-gui_macos_universal_dmg_x.x.x.dmg	✅	DMG installer
macOS Universal	tyutool-gui_macos_universal_portable_x.x.x.tar.gz	❌	Extract and run
Linux x86_64	★ tyutool-gui_linux_x86_64_appimage_x.x.x.AppImage	✅	chmod +x then run; cross-distro
Linux aarch64	★ tyutool-gui_linux_aarch64_appimage_x.x.x.AppImage	✅	chmod +x then run; cross-distro
Linux x86_64	tyutool-gui_linux_x86_64_deb_x.x.x.deb / _rpm_x.x.x.rpm	❌	Debian-family / Fedora·RHEL-family
Linux aarch64	tyutool-gui_linux_aarch64_deb_x.x.x.deb	❌	Debian-family
Linux x86_64 / aarch64	tyutool-gui_linux_*_portable_x.x.x.tar.gz	❌	Unpack and run

Troubleshooting

Issue	Platform	Fix
"cannot be opened because the developer cannot be verified" / Gatekeeper block	macOS	Builds are not Apple-signed — this is expected. System Settings → Privacy & Security → Open Anyway; or Control-click tyutool.app in Finder → Open
No serial port listed	macOS	System Settings → Privacy & Security → Accessories (label varies by macOS version)
Blank / white window (common in VMs)	Linux	WebKit2GTK GPU compositing failure. Set the environment variable before launching: export WEBKIT_DISABLE_COMPOSITING_MODE=1, then run ./tyutool-gui_linux_x86_64_appimage_x.x.x.AppImage

CLI

Platform	File
Linux x86_64	tyutool-cli_linux_x86_64_<ver>.tar.gz
Linux aarch64	tyutool-cli_linux_aarch64_<ver>.tar.gz
macOS x86_64	tyutool-cli_macos_x86_64_<ver>.tar.gz
macOS aarch64	tyutool-cli_macos_aarch64_<ver>.tar.gz
Windows x86_64	tyutool-cli_windows_x86_64_<ver>.zip

Extract and run tyutool_cli (or tyutool_cli.exe on Windows).

Update Manifests (latest.json / release.json)

Every release attaches two update manifests to the GitHub Release, generated by CI (scripts/generate-manifest.ts). They share the same content — version, release notes, and per-platform entries for the GUI updater (platforms), CLI (cli), and portable packages (portable) — and differ only in which mirror the active url points at:

Manifest	Audience	Active url	Update-check endpoint
latest.json	Overseas	GitHub Release assets (url = url_github)	https://github.com/tuya/tyutool/releases/latest/download/latest.json
release.json	Mainland China	Tuya OSS mirror (url = url_tuya)	https://airtake-public-data-1254153901.cos.ap-shanghai.myqcloud.com/smart/embed/pruduct/tyutool/latest/release.json

Each download entry carries three URL fields:

• url — the URL clients actually download from; the only field the GUI updater and CLI self-update read.
• url_github — the GitHub Release asset URL (mirror field, for external systems).
• url_tuya — the Tuya OSS mirror URL (mirror field, for external systems).

Note: For scripted downloads of release artifacts, fetch the latest release.json (https://github.com/tuya/tyutool/releases/latest/download/release.json) first, then pick the download URL from each entry by region: url_tuya for mainland China, url_github overseas.

CLI Usage

tyutool <COMMAND>

Flash firmware

# Auto-detect port, default baud 921600
tyutool write -d bk7231n -f firmware.bin

# Specify port
tyutool write -d bk7231n -p /dev/ttyUSB0 -f firmware.bin

# Full options
tyutool write -d <DEVICE> -p <PORT> -b <BAUD> -s <START_ADDR> --end <END_ADDR> -f <FILE>

Supported -d values: bk7231n, t2, t5ai

Read flash

# Read 2 MB from address 0x0 (default)
tyutool read -d bk7231n -p /dev/ttyUSB0 -f dump.bin

# Custom range
tyutool read -d t5ai -p /dev/ttyUSB0 -s 0x0 -l 0x100000 -f dump.bin

List serial ports

tyutool list-ports

Device authorization

# Read current auth state
tyutool authorize -p /dev/ttyUSB0

# Write UUID and AuthKey
tyutool authorize -p /dev/ttyUSB0 --uuid <UUID> --authkey <AUTHKEY>

Reset device

tyutool reset -p /dev/ttyUSB0 -d bk7231n

Serial monitor

# Stream device output (quit with Ctrl+] or Ctrl+C)
tyutool monitor -p /dev/ttyUSB0

# T5AI default monitor baud (460800), tee output to a file
tyutool monitor -p /dev/ttyUSB0 -d t5ai -l device.log

Self-update

# Check latest version
tyutool update --check

# Update from GitHub (default)
tyutool update

# Update from Tuya OSS mirror (mainland China)
tyutool update --source tuya

Verbose logging

RUST_LOG=debug tyutool write -d bk7231n -f firmware.bin

Build from Source

Prerequisites: Rust (stable), Node.js 22+, pnpm 10+

Use pnpm to install dependencies (pnpm-lock.yaml). Do not run npm install — it creates a conflicting package-lock.json.

Windows development

Dependency	Notes
Node.js 22+	v24 works; enough for frontend-only builds
pnpm 10+	If missing: npm install -g pnpm, then restart the terminal
Rust (stable)	Required for GUI / CLI / dev:web — rustup.rs
VS Build Tools	Tauri needs MSVC — install Build Tools with Desktop development with C++

pnpm install
pnpm run build          # Verify frontend (Node + pnpm only)
pnpm run tauri:dev      # GUI dev (also needs Rust)

Common issues:

• pnpm install → ERR_PNPM_IGNORED_BUILDS — pnpm 10+ blocks postinstall scripts by default. This repo whitelists esbuild and lefthook in pnpm-workspace.yaml; if it still fails, run pnpm approve-builds esbuild lefthook and retry.
• cargo / program not found — Rust not installed, or the terminal was opened before rustup; install Rust and open a new terminal.

CLI only

cargo build -p tyutool-cli --release
# Output: target/release/tyutool_cli

Desktop GUI

pnpm install
pnpm run tauri:build

Development

pnpm install
pnpm run tauri:dev   # GUI dev (Tauri + hot-reload; requires Rust)
pnpm run dev         # Vite frontend only (no Tauri, no CLI serve)
pnpm run dev:web     # Browser dev: tyutool-cli serve + Vite (cross-platform)

Architecture

tyutool/
├── crates/
│   ├── tyutool-core/   # Rust library — all flash logic, chip plugins, serial utils
│   └── tyutool-cli/    # Standalone CLI binary (depends on tyutool-core only)
├── src-tauri/          # Tauri 2 shell (Rust backend for the desktop GUI)
└── src/                # Vue 3 frontend (Vite, Pinia, Tailwind CSS, DaisyUI)

tyutool-core is shared by both the GUI and CLI. Flash logic lives there and is never duplicated.

License

Apache-2.0 — see LICENSE.txt.