Skip to content

Release firmware with the CLI

The CLI is in beta, as the install page explains.

Every command has --help with examples, and --json prints machine-readable output (schema).

Log in

The CLI uses an API token you make in the dashboard.

Token Prefix Reaches Make it
Personal soto_pat_ Every project your account can open API tokens in the account menu
Project soto_proj_ One project Issue token on the project page, with the api scope

Use a personal token on your own machine, and a project token in CI. See Tokens for the scopes. A device-scope token cannot upload or deploy.

simpleota login

Paste the token at the prompt. In a graphical session (not over SSH), pressing Enter at the prompt instead opens the API tokens page in your browser; --no-browser turns that off. You can also pipe the token in:

echo "$SIMPLEOTA_TOKEN" | simpleota login

The token is checked with the server, then stored in the OS keychain, or in a 0600 file in the config directory when there is no keychain (or SIMPLEOTA_NO_KEYRING is set). If SIMPLEOTA_TOKEN is set, it is used instead of the stored token.

Check what the CLI will act on:

simpleota status

status shows the CLI's version, the account, the current project and the signing key new builds would be signed with.

Choose a project

Most commands act on the current project, the first of these that applies:

  1. --project <slug|id>
  2. SIMPLEOTA_PROJECT
  3. the project chosen with simpleota project use (personal tokens only)
  4. the only project the token can see; a project token sees just its own
simpleota project list
simpleota project use my-fleet

Projects are created in the dashboard.

Make a signing key

Skip this section to release basic (unsigned) builds.

simpleota key generate --key-id prod-2026

This makes an Ed25519 key pair on your machine, saves the private key encrypted with a passphrase you choose, and registers only the public key with the project. The first key you generate becomes the default for signing. key generate needs a personal token.

Devices pin at most two keys, so make a backup key before your first signed release and keep it offline:

simpleota key generate --key-id backup-2026 --out /Volumes/usb/backup.key

Each key generate prints a signing_keys snippet for the 1.0 Arduino and ESP-IDF clients that pins the new key and your default key, so the backup key's snippet pins both. Put that one in your firmware. See Signed firmware for what the device checks and how to rotate or revoke a key.

Release a build

release signs, uploads and deploys a binary in one step:

simpleota release build/app.bin --version-label 1.0.0 --percent 10
  • Pass the application image: build/<sketch>.ino.bin from Arduino, or build/<project>.bin from ESP-IDF. The CLI refuses the bootloader, partition table, merged and filesystem images it can recognise by name.
  • The chip is read from the image header. The framework defaults to the project's; pass --framework arduino or --framework esp_idf to override it.
  • The build is signed with the first key found: --key-file, then SIMPLEOTA_SIGNING_KEY, then your default key. With no key it is uploaded as basic. --security-mode basic or --security-mode signed makes the choice explicit.
  • The server assigns the build number.
  • The deployment goes to the stable channel unless you pass --channel, which must name an existing channel. --percent defaults to 100.

The result names the build, the deployment ID, and the count of active devices in the deployment's audience whose last reported metadata is compatible with the build. That count ignores the rollout percentage, and a device's next check-in can change it.

The upload is sent once and never retried, because every accepted upload uses a build number and counts toward your plan's monthly limit. If the project already has this binary, release stops before uploading, so it is safe to run again after a failed upload. If the first upload was accepted, for example when the connection dropped after the server took it, the rerun exits 1 without uploading or deploying. It then names the existing build and any deployment of it that is still running or paused. If none is listed, deploy the build with simpleota deployment create --build <n>, passing the same --channel and --percent. Pass --allow-duplicate to upload the same bytes as a new build.

Upload now, deploy later

simpleota build upload build/app.bin --version-label 1.0.0
simpleota deployment create --build 42 --channel beta --percent 10

deployment create targets channels (--channel), device groups (--group), or every device (--all-devices). Repeat --channel or --group for more than one. With both, a device must match one of each.

Manage deployments

Command What it does
simpleota deployment list List deployments, newest first
simpleota deployment show [id] Show the build, state, percentage and device counts; the newest deployment without an ID
simpleota deployment devices [id] List the compatible devices the release count included
simpleota deployment ramp <id> --percent 50 Raise the percentage. It cannot go down
simpleota deployment pause <id> Stop offering the build
simpleota deployment resume <id> Offer it again at the same percentage
simpleota deployment complete <id> Mark the deployment finished
simpleota deployment cancel <id> Stop the deployment for good

In a project with two or more devices, resuming a deployment that targets every device needs --all-devices again.

Several deployments can be active on one channel, and each device installs the highest build offered to it. release lists the other active deployments for the same chip on its channel; stop one with deployment complete.

There is no rollback command: devices are never offered a build at or below the one they run. To go back, release the previous source again as a new, higher build. See Promoting deployments and Pausing deployments.

Other commands

Command What it does
simpleota device list List devices, filtered by --channel, --group or --state
simpleota device show <device> Show one device
simpleota device events <device> Show its recent update checks and why it was or was not offered a build
simpleota device update <device> --channel beta Move a device to a channel; --name and --state rename or (de)activate it
simpleota channel list, channel create <name> List or create release channels
simpleota group list, group create <name> List or create device groups
simpleota group member add <group> <device>... Add devices to a group; list and remove work the same way
simpleota build list, build show <n> List builds or show one
simpleota build archive <n> Take a build out of service; unarchive returns it
simpleota audit Show the project's audit log

Name a device by the device ID its firmware reports, such as a MAC address, or by its SimpleOTA UUID. Devices register themselves on their first check-in.

In CI

You need three secrets:

  • SIMPLEOTA_TOKEN: a project token with the api scope, issued for the job.
  • SIMPLEOTA_SIGNING_KEY: the encrypted private key, from simpleota key export on the machine that holds it.
  • SIMPLEOTA_SIGNING_KEY_PASSPHRASE: its passphrase.

For example, with the GitHub CLI:

simpleota key export | gh secret set SIMPLEOTA_SIGNING_KEY

A project token acts on its own project, so the job needs no --project. Install a pinned version on the runner, then release with --require-devices:

- name: Install the SimpleOTA CLI
  run: |
    curl -fsSL https://github.com/wassie-dev/simpleOTA-cli/releases/download/v0.2.0/install.sh | SIMPLEOTA_VERSION=0.2.0 SIMPLEOTA_INSTALL_DIR="$HOME/.local/bin" SIMPLEOTA_NO_MODIFY_PATH=1 sh
    echo "$HOME/.local/bin" >> "$GITHUB_PATH"

- 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

Define the three secrets as CI/CD variables. The job image needs curl or wget, tar, and sha256sum or shasum.

release-firmware:
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - curl -fsSL https://github.com/wassie-dev/simpleOTA-cli/releases/download/v0.2.0/install.sh | SIMPLEOTA_VERSION=0.2.0 SIMPLEOTA_INSTALL_DIR="$HOME/.local/bin" SIMPLEOTA_NO_MODIFY_PATH=1 sh
    - export PATH="$HOME/.local/bin:$PATH"
    - simpleota release build/app.bin --version-label "$CI_COMMIT_TAG" --percent 10 --require-devices

Devices may check in only once a day, so the job does not wait for them. With --require-devices, the job fails with exit code 4 when no active device in the audience has reported metadata compatible with the build. The deployment stays active, and you can follow it afterwards with simpleota deployment show.

On GitHub, the SimpleOTA actions do the same job as workflow steps.

Exit codes

Code Meaning
0 OK
1 Error, or the command was interrupted
2 Usage error, including no current project when the token sees several
3 Not logged in, or the token was rejected
4 With --require-devices, no active device in the audience has compatible metadata

With --require-devices, an unknown count exits 1, for example when the server is too old to report it.

Environment variables

Variable Use
SIMPLEOTA_TOKEN API token; used instead of the stored one
SIMPLEOTA_PROJECT Project slug or ID; used instead of project use
SIMPLEOTA_SIGNING_KEY Exported key, encrypted or PEM
SIMPLEOTA_SIGNING_KEY_PASSPHRASE Passphrase for an encrypted key
SIMPLEOTA_API_URL API URL (default https://simpleota.com)
SIMPLEOTA_CONFIG_DIR Config directory (default: the OS user config directory)
SIMPLEOTA_NO_KEYRING Store the token in a 0600 file instead of the keychain
SIMPLEOTA_DOWNLOAD_URL Mirror for update downloads (https, or http on localhost)
NO_COLOR Turn off colour