SimpleOTA
All posts
5 min read Alexander Wasserman

The SimpleOTA CLI is out in beta

The SimpleOTA CLI is in beta. Install it with one command, sign ESP32 firmware on your own machine, and release from a laptop or CI with a gradual rollout.

releases cli security ci

SimpleOTA now has a command-line tool. SimpleOTA CLI 0.2.0 came out on 18 November, and it signs your ESP32 firmware on your machine, uploads it, rolls it out to a share of your fleet and can fail a CI job when no active device in the deployment’s audience has reported compatible metadata. It talks to the same projects you already use through the dashboard, the dev API or the GitHub Actions.

I’m calling it a beta. The version number is still 0.x, and you should expect some commands and output to change before 1.0. The source is on GitHub under the MIT license.

Installing it

0.2.0 ships install.sh, install.ps1, a checksums.txt and archives for Linux, macOS and Windows on amd64 and arm64. On Linux and macOS:

curl -fsSL https://github.com/wassie-dev/simpleOTA-cli/releases/latest/download/install.sh | sh

On Windows, in PowerShell:

irm https://github.com/wassie-dev/simpleOTA-cli/releases/latest/download/install.ps1 | iex

The script picks the archive for your OS and CPU, checks it against the release’s checksums.txt, and installs it without sudo. If the install directory isn’t on your PATH yet, it adds it, so open a new terminal afterwards. To update later, run simpleota update. If you’d rather build it yourself, Go 1.27.4 or newer works too:

go install github.com/wassie-dev/simpleOTA-cli/cmd/simpleota@latest

A first release from your laptop

# 1. Paste a personal token, made under API tokens in the dashboard's
#    account menu (kept in the OS keychain)
simpleota login
simpleota status

# 2. Choose the project to work on (skip this if you have only one)
simpleota project list
simpleota project use my-fleet

# 3. Create a signing key; the private key stays here, encrypted
simpleota key generate --key-id prod-2026

# 4. Pin the printed signing_keys snippet in your firmware, then release
simpleota release build/app.bin --version-label 1.0.0 --percent 10

# 5. Follow the rollout's device counts, then widen it
simpleota deployment show
simpleota deployment ramp <deployment-id> --percent 100

key generate prints a signing_keys snippet that you paste into your firmware, the same pinned keys the 1.0 Arduino and ESP-IDF clients check against in signed mode. Devices pin at most two keys and can’t change them over the air, so the README suggests running key generate a second time for a backup key, keeping that one offline, and pinning both in your first signed firmware (the second run’s snippet already holds both).

release reads the chip family from the image header, signs the binary, uploads it and starts a deployment to 10% of the devices on the stable channel, which release uses unless you pass --channel. It sends the upload exactly once and never retries it, because every accepted upload takes a new build number. If the connection drops mid-upload, it lists what the server has for that binary and exits, and running the same command again stops at the existing build instead of making a second one.

There is no rollback command: SimpleOTA never offers a build at or below the one a device runs. To go back you release the previous source again, and it gets a new, higher build number. If the rebuilt binary is byte-for-byte the earlier one, release stops because the project already has it, and --allow-duplicate uploads it again.

Every command has --help with examples, the CLI docs are on the wiki, and the README is the full reference for every command, environment variable and exit code.

Releasing from CI

In CI you use an api-scoped project token from the dashboard and the signing key you exported once with simpleota key export, both stored as secrets, and you put simpleota on the runner’s PATH from the releases page. In GitHub Actions the step looks like this:

- name: Release firmware
  env:
    SIMPLEOTA_TOKEN: ${{ secrets.SIMPLEOTA_TOKEN }}
    SIMPLEOTA_SIGNING_KEY: ${{ secrets.SIMPLEOTA_SIGNING_KEY }}
    SIMPLEOTA_SIGNING_KEY_PASSPHRASE: ${{ secrets.SIMPLEOTA_SIGNING_KEY_PASSPHRASE }}
  run: simpleota release build/app.bin --version-label "${GITHUB_REF_NAME}" --percent 10 --require-devices

The README has the GitLab CI version as well. Devices may check in only once a day, so the job doesn’t wait for them to install anything. --require-devices looks at the server’s count of active devices in the deployment’s audience whose last reported metadata is compatible with the build. If that count is 0, the command exits 4 and the job fails while the deployment stays active. You follow the rollout afterwards with simpleota deployment show.

simpleOTA-actions v1.1.0 now uses the CLI as well. In a signed job it downloads the pinned CLI 0.2.0 on the runner and checks it against a pinned checksum (a simpleota already on the runner’s PATH is used instead), then uses the CLI for one best-effort step after the upload. That step never fails the job. Unsigned jobs install nothing, and since the v1 tag now points at v1.1.0, a workflow on @v1 needs no changes.

Your signing key stays with you

key generate creates an Ed25519 key on your machine and keeps the private half there, encrypted with a passphrase. SimpleOTA never holds the private key and only receives the public key and the signatures the CLI makes, so someone who gets into your SimpleOTA account can’t make a device in signed mode accept firmware you didn’t sign. When you export the key for CI, it goes into your CI secrets, and the runner signs with it locally in the same way, so treat that secret as the key itself.

Signing protects the delivery path between your build and the device: a device in signed mode checks the signature against its pinned keys before it marks the new image bootable. It doesn’t replace Secure Boot, and you can run both. The signed firmware guide covers how they fit together.