Skip to content

SimpleOTA CLI (beta)

simpleota is the command-line tool for SimpleOTA. It signs ESP32 firmware on your machine, uploads it, starts and changes deployments, and, with --require-devices, fails a CI job when no active device in the deployment's audience has reported compatible metadata. It works through the developer API.

Beta

The CLI is in beta. The current release is 0.2.0. Commands, flags and output can change between releases, so pin a version in CI. Report problems on the CLI's issue tracker, and security issues as its SECURITY.md describes.

Signing keys are made and kept on your machine, and only public keys and signatures are sent to SimpleOTA, which never holds your private key.

Install

Releases are built for Linux, macOS and Windows, on amd64 and arm64.

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

The script needs curl or wget, tar, and sha256sum or shasum. It installs without sudo, in the first of these that applies:

  1. the directory simpleota is already in, if it is writable
  2. /usr/local/bin, if it is writable
  3. ~/.local/bin

If that directory is not on your PATH, the script adds one line to your shell's startup file: ~/.zshrc for zsh, ~/.bash_profile on macOS or ~/.bashrc on Linux for bash, conf.d/simpleota.fish for fish, and ~/.profile otherwise. Open a new terminal afterwards.

In PowerShell:

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

The script installs simpleota.exe in %LOCALAPPDATA%\Programs\simpleota and adds that folder to your user PATH. Open a new terminal afterwards.

Both scripts download the archive for your OS and CPU and check it against the release's checksums.txt before installing it. Check the install with:

$ simpleota --version
simpleota version 0.2.0

Install options

The scripts read these environment variables:

Variable Use
SIMPLEOTA_VERSION Install a specific version, for example 0.2.0. The default is the latest release.
SIMPLEOTA_INSTALL_DIR Install somewhere else.
SIMPLEOTA_NO_MODIFY_PATH=1 Leave your PATH and shell startup files alone.

To pin a version:

curl -fsSL https://github.com/wassie-dev/simpleOTA-cli/releases/download/v0.2.0/install.sh | SIMPLEOTA_VERSION=0.2.0 sh
$env:SIMPLEOTA_VERSION = '0.2.0'
irm https://github.com/wassie-dev/simpleOTA-cli/releases/download/v0.2.0/install.ps1 | iex

Without the script

Download the archive for your platform from the release page and check it against checksums.txt. Each archive holds the simpleota binary (simpleota.exe on Windows), the README and the licence. On macOS, a browser download is quarantined until you run xattr -d com.apple.quarantine simpleota.

With Go 1.27.4 or later you can build it instead:

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

Update

simpleota update            # install the latest release
simpleota update --check    # only report whether there is one

update checks the download against the release's checksums.txt before replacing the binary. If the binary's folder is not writable, run the install script again instead. simpleota status also says whether a newer release exists.

Uninstall

  1. Run simpleota logout to remove the stored token.
  2. Delete the simpleota binary.
  3. Delete the config directory: ~/.config/simpleota on Linux, ~/Library/Application Support/simpleota on macOS, %APPDATA%\simpleota on Windows.

The config directory holds the private keys made by simpleota key generate, in keys/. Keep a copy of every key your devices pin before you delete it: without the key, you cannot sign builds those devices accept.

Next

Release firmware with the CLI goes on from here, from logging in to a first release and a CI job.