CLI & TUI (raptorctl)

raptorctl is a separate binary (crate raptor-cli) that drives a running raptor server over the same Management API the web console uses. It is a pure HTTP client — install it anywhere that can reach raptor serve, no server-side changes required.

Login

$ raptorctl login --url http://localhost:8088 --user admin
password for admin: 
logged in as admin

This verifies the credentials with a request against the server, then saves them to ~/.config/raptor/cli.toml (mode 0600). Every later command reuses that file, so --url/--user are only needed again to switch servers.

raptorctl logout deletes the saved file.

Scripting / CI

Skip the config file entirely with environment variables — useful in CI where there’s no interactive prompt for login to read a password from:

$ RAPTOR_URL=http://localhost:8088 RAPTOR_USER=admin RAPTOR_PASS=secret \
    raptorctl target list

Precedence is flags > environment > the saved config file.

Commands

Every command accepts --json to print the server’s raw response instead of a table — pipe it into jq:

$ raptorctl target list --json | jq '.content[].controllerId'

Run raptorctl <command> --help for full flag lists.

publish and the two type vocabularies

publish creates a software module, uploads the file to it, and wraps it in a distribution set. Those are typed from two different hawkBit vocabularies:

--ds-type is optional: raptorctl reads /rest/v1/softwaremoduletypes and /rest/v1/distributionsettypes and derives it — an exact key match wins (os → os), otherwise the one set type that requires exactly that module type (application → app). When neither applies (e.g. --module-type firmware, which no seeded set type requires) it errors and asks for --ds-type rather than guessing, because a wrong guess builds an incomplete distribution set that only fails later, at assign time.

Both types are validated against the server before anything is written. That ordering matters: the sequence is create-module → upload → create-set, so a type rejected at the last step would leave an orphaned module and a multi-megabyte artifact behind, with no module/ds delete subcommand to clean them up.

Withdrawing a release

ds invalidate is the inverse of publish: the set can no longer be assigned or rolled out, and any target filter auto-assigning it is detached. There is no undo.

$ raptorctl ds invalidate 7
invalidate distribution set 7 (fw:1.4.1)? this cannot be undone. [y/N] y
invalidated distribution set 7 (fw:1.4.1)

The bare command is the safe one, because it is the one that gets run in a hurry: in-flight actions and rollouts are left alone, so a device that has already installed the set still reports its result. The destructive parts are opt-in:

The prompt only appears when stdin is a TTY, so scripts and CI need no --yes. ds get reports the result as valid false.

Tags

tag manages the tag itself; target tag/ds tag only assign an existing one to something. --ds switches every tag subcommand from target tags to distribution-set tags.

$ raptorctl tag create zephyr --description 'Zephyr firmware fleet' --colour '#4caf50'
created target tag 3 (zephyr)
$ raptorctl tag list
ID  NAME    DESCRIPTION            ASSIGNED
3   zephyr  Zephyr firmware fleet  0
$ raptorctl target tag add dev-042 zephyr
tagged dev-042 with zephyr

Assigning a tag that doesn’t exist names the ones that do, so a typo and a never-created tag are distinguishable:

$ raptorctl target tag add dev-042 zephry
error: no target tag named 'zephry' — existing: zephyr, prod. Create it with 'raptorctl tag create zephry'.

Target types

A target type constrains which distribution-set types the target will accept, so it is a correctness setting rather than an organisational one — an incompatible assignment is rejected at assign time.

$ raptorctl target type list
ID  NAME     DESCRIPTION  ACCEPTS_DS_TYPES
1   gateway  -            os
$ raptorctl target type set dev-042 gateway
dev-042 is now target type gateway (1)
$ raptorctl target get dev-042 | grep targetType
targetType    gateway
$ raptorctl target assign dev-042 --ds 7
error: distribution set type 'app' is not compatible with target type 'gateway', which accepts: os (HTTP 400)

raptorctl target type clear <cid> removes the constraint. Creating target types themselves is not in the CLI yet — use the console or POST /rest/v1/targettypes.

Rollout approval

When the server runs with rollout_approval_enabled = true, a new rollout waits in waiting_for_approval until an operator decides on it:

$ raptorctl rollout list
ID  NAME       STATUS                FINISHED  DECIDED BY
7   fw-1.4.2   waiting_for_approval  0/240

$ raptorctl rollout approve 7 --remark "checked with ops"
rollout 7 is now ready

deny is the other half, and is terminal — a denied rollout can only be deleted, so create a fresh one to try again. Both take an optional --remark recorded against the decision. See the Rollouts guide.

End-to-end example

$ raptorctl module create --name fw --version 1.4.1 --type os
$ raptorctl artifact upload 1 ./firmware.bin
$ raptorctl ds create --name fw --version 1.4.1 --type os --module 1
$ raptorctl target create dev-042
$ raptorctl target assign dev-042 --ds 1 --force forced
$ raptorctl target get dev-042

TUI

raptorctl tui opens an interactive dashboard: the fleet on the left, the selected target’s status, assigned/installed set, and action history on the right, and running rollouts underneath the target list.

$ raptorctl tui [--refresh <seconds>]   # default 5, 0 disables auto-refresh

It respects NO_COLOR, works over SSH and inside tmux, and requires at least an 80x24 terminal.