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.
The script needs curl or wget, tar, and sha256sum or shasum. It
installs without sudo, in the first of these that applies:
- the directory
simpleotais already in, if it is writable /usr/local/bin, if it is writable~/.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.
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:
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:
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:
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¶
- Run
simpleota logoutto remove the stored token. - Delete the
simpleotabinary. - Delete the config directory:
~/.config/simpleotaon Linux,~/Library/Application Support/simpleotaon macOS,%APPDATA%\simpleotaon 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.