kx command line

kx runs commands and scripts on your devices from a terminal or a CI pipeline, follows their output live and exits with the result, so a release or a patch step can fail the pipeline when a device fails. It uses the API with an API token.

Install

kx is one file and needs Node.js 18 or later (CI images of GitHub Actions and GitLab have it).

curl -fsSL https://apt.kinuxota.com/kx -o kx
curl -fsSL https://apt.kinuxota.com/kx.sha256 | sha256sum -c -
sudo install -m 755 kx /usr/local/bin/kx
kx --version

A version stays at its own address for pipelines that pin it: https://apt.kinuxota.com/kx/1.0.0/kx (and kx.sha256 next to it).

Sign in

Make a token in Team > API tokens (an operator token runs commands and scripts; see API tokens), then:

kx login            # asks for the token, checks it and saves it in ~/.config/kinuxota/kx.json (mode 600)
kx whoami           # Acme (operator)

In CI, set the KX_TOKEN secret instead of logging in. KX_URL changes the API address (default https://back.kinuxota.com).

Use

kx devices                                  # name, status, OS, agent version, last seen, id
kx scripts                                  # name, parameters (? = optional), id
kx exec "systemctl restart nginx" --device web-1
kx exec "df -h /" --all                     # every device; each line starts with the device's name
kx run "Update packages" --device web-1 --device web-2 --param REBOOT=false

Devices are named by name or id (--device, repeatable) or all at once (--all); scripts by name or id. Devices that are offline get the command when they connect; kx says which ones and waits.

Option
--timeout SECONDS	The device stops the command or script after this long (default 3600).
--max-wait SECONDS	Stop following after this long and exit 124 (default 3600); it keeps running.
--no-wait	Start it, print the ids and exit 0.
--json	No live output; one JSON document at the end with each device's status, exit code and output.
--param NAME=VALUE	(run) A parameter value; repeatable.
--offline-wait SECONDS	(run) How long offline devices may take to come online.

Exit codes

Code	Meaning
0	Finished successfully on every device.
n	On one device: the command's or script's own exit code.
1	It failed on one or more devices (each one's result is printed on stderr).
2	Wrong usage, an unknown device or script.
3	No token, or the token is wrong, expired or revoked.
4	The API refused it (for example, the token's role may not run commands) or could not be reached.
124	--max-wait reached.

Output from the devices goes to stdout; kx's own messages go to stderr.

In a pipeline

# GitHub Actions
- name: Restart the service on the staging devices
  env:
    KX_TOKEN: ${{ secrets.KINUXOTA_TOKEN }}
  run: |
    curl -fsSL https://apt.kinuxota.com/kx/1.0.0/kx -o kx && chmod +x kx
    ./kx run "Deploy app" --device staging-1 --device staging-2 --param VERSION=${{ github.sha }}

An organisation token suits pipelines: it keeps working when the person who made it leaves, and the audit log shows its name on everything it did.