Installation

phpflash is a single static Go binary. It scaffolds a project, drives the ESP-IDF build, flashes the board, and opens the serial console — replacing php-esp32's setup.sh, flash.sh and monitor.sh with one consistent tool. Installing it is a matter of putting one binary on your PATH.

Nothing else is installed at this point. The cross-toolchain (ESP-IDF) and the php-esp32 firmware sources come later, in one step, via phpflash system-setup.

Host requirements

• A POSIX host: Linux or macOS. Prebuilt release binaries are published for Linux; on macOS, build from source.
• Go 1.25+ — only to build from source. A prebuilt binary needs nothing.
• A supported board over USB, and a USB cable that carries data. The boards themselves are documented in php-esp32.

From a release (Linux)

Each release ships per-architecture binaries and a SHA256SUMS checksum file. The latest/download URL always points at the newest release, so this fetches the current binary, verifies its checksum, and installs it:

BASE=https://github.com/php-baremetal/flash-tool/releases/latest/download
curl -LO "$BASE/phpflash-linux-amd64"      # or phpflash-linux-arm64
curl -LO "$BASE/SHA256SUMS"
sha256sum --ignore-missing -c SHA256SUMS
chmod +x phpflash-linux-amd64
sudo mv phpflash-linux-amd64 /usr/local/bin/phpflash
phpflash --version

Two Linux architectures are published: phpflash-linux-amd64 and phpflash-linux-arm64. Pick the one that matches your host.

From source

With Go 1.25+ installed, clone the flash-tool repository and build the binary:

go build -o phpflash .

Then put the resulting phpflash somewhere on your PATH (for example /usr/local/bin). This is the route to use on macOS, where no prebuilt binary is published.

Verify the install

Confirm the binary is on your PATH and runs:

phpflash --version

Every command also accepts --help, so phpflash <command> --help prints that command's full flag list at the terminal.

Next: install the toolchain and firmware sources

Installing the binary does not install ESP-IDF or the firmware. That happens once per machine, with a single command:

phpflash system-setup

This clones ESP-IDF and runs its installer (which brings the cross-compilers and a private Python environment), then clones php-esp32 and runs its scripts/fetch-php.sh to download and patch the PHP source. It is idempotent — run it again later and it updates the checkouts rather than re-cloning. By default both land under ~/esp; override with --idf-path and --php-esp32-path.