IronFlock CLI
ironflock is the command line tool for the IronFlock software on a machine. You use it to connect a Linux machine to IronFlock as a device, to write IronFlockOS to a USB stick, an SD card or a disk, to replace the Linux of a running machine with IronFlockOS, to update, roll back and reset IronFlockOS devices, and to install and look after an IronFlock appliance.
ironflock is one static binary per platform. It needs no runtime and no other package. Install it on Linux or macOS with one line:
curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bashThe script checks the download against the IronFlock release key before it installs /usr/local/bin/ironflock. Later, sudo ironflock self-update brings it to the newest release. Installation explains each step, how to verify the script first, and how to update.
The commands are grouped by product: ironflock agent for the device agent, ironflock appliance for the IronFlock appliance, ironflock os for IronFlockOS. A verb means the same in every group. Commands about the machine as a whole, such as ironflock status, have no group. ironflock --help lists the commands, and ironflock <command> --help describes one.
Commands by Task
| Task | Command | Reference |
|---|---|---|
Connect a Linux machine to IronFlock as the device of a device configuration file (.flock) | ironflock agent install | Device Agent Commands |
Give the installed agent another .flock file or other proxy settings | ironflock agent configure | Device Agent Commands |
| Let the agent update itself to the release of its channel | ironflock agent update | Device Agent Commands |
| Remove the agent and undo what its install changed | ironflock agent remove | Device Agent Commands |
| Restart the device agent | ironflock agent restart | Device Agent Commands |
| Stop the device agent until it is started again | ironflock agent stop | Device Agent Commands |
| Start the device agent | ironflock agent start | Device Agent Commands |
| Read the device agent’s log | ironflock agent logs | Device Agent Commands |
| See what of IronFlock is on a machine and whether it runs | ironflock status | Status & Doctor |
| Check whether a machine can run the device agent and reach IronFlock | ironflock doctor | Status & Doctor |
| List the IronFlockOS images that can be written to a drive | ironflock os images | Write IronFlockOS to a Drive |
| List the drives an image can be written to | ironflock os drives | Write IronFlockOS to a Drive |
Write IronFlockOS and a device’s .flock file to a drive or an image file | ironflock os flash | Write IronFlockOS to a Drive |
| Replace the Linux of a running machine with IronFlockOS | ironflock os install | Replace Linux with IronFlockOS |
| Update an IronFlockOS device to the release of its channel | ironflock os update | Update, Roll Back & Reset |
| Go back to the IronFlockOS system in the other slot | ironflock os rollback | Update, Roll Back & Reset |
| Reset an IronFlockOS device to a freshly written one | ironflock os reset | Update, Roll Back & Reset |
| Install, configure, update and look after an IronFlock appliance on this machine | ironflock appliance | Appliance Commands |
Show the version of ironflock, and whether a newer release is out | ironflock version, ironflock version --check | Installation |
Replace ironflock with the newest release | ironflock self-update | Installation |
| Complete command lines with the Tab key | ironflock completion | Installation |
| Run a command on another machine over SSH, or on many | --host, --hosts | Remote Machines over SSH |
Every command takes the global flags. Among them are --yes, which answers the command’s question, and --json, which writes the result as one JSON object for a program to read.
# Install ironflock and connect this Linux machine as the device of device.flock, in one line
curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash -s -- agent install -c device.flock
# Check whether this machine can run the device agent and reach the hosts of device.flock
ironflock doctor -c device.flock
# Write IronFlockOS for the device of device.flock to the drive /dev/sdb
sudo ironflock os flash -c device.flock -d /dev/sdb
# Show the plan for replacing this machine's Linux with IronFlockOS, and change nothing
sudo ironflock os install -c device.flock --dry-run
# Show the state of a device from your laptop, over SSH
ironflock --host pi@device-17 statusSystems
The release publishes ironflock for Linux on amd64, arm64 and 32-bit ARM (v5 to v7), and for macOS on Apple silicon and Intel.
| Commands | Linux | macOS |
|---|---|---|
version, completion | yes | yes |
self-update | yes; on an IronFlockOS device exit code 3, as os update updates ironflock there | yes |
status, doctor | yes | yes; status shows the system and that nothing is installed |
os images, os drives, os flash | yes | yes |
agent ..., os install | yes | exit code 3 |
os update, os rollback, os reset | on an IronFlockOS device only | exit code 3 |
A command that does not run on a system is there all the same: it ends with exit code 3 before it looks at anything. The agent commands need a Debian or Ubuntu based Linux with systemd. os install needs a Linux with systemd on 64-bit UEFI firmware (amd64 or arm64). The appliance commands are described on Appliance Commands.
On an IronFlockOS device, the image brings the device agent with its system. agent install and agent remove therefore refuse there with exit code 3, and agent configure -c gives the device another .flock file.
With --host, every command but completion runs on another Linux machine over SSH. From a Mac you run the agent commands, os install and the commands of an IronFlockOS device this way.
IronFlockOS releases after 0.15.0 carry ironflock on the device, as /usr/bin/ironflock. IronFlockOS 0.15.0 and older do not: run the device’s commands from another computer with --host, as the device’s SSH user (SSH Access):
ironflock --host operator@kitchen-pc os update --reboot --yesNote: The command’s messages and JSON fields say swarm for what IronFlock Studio and these docs call a project, and “swarm owner” for the project owner. For example, the field
agent.swarmofironflock status --jsonnames the device’s project.
In This Section
- Installation: the install line, verifying the script, the download base and an appliance’s mirror, tab completion,
ironflock versionandironflock self-update. - Flags, Output & Exit Codes: the global flags, stdout and JSON, questions, root, secrets and exit codes, which hold for every command.
- Remote Machines over SSH:
--hostfor one machine,--hostsand--parallelfor many. - Device Agent Commands: install, configure, update, remove, restart, stop and start the device agent, and read its log.
- Status & Doctor: what of IronFlock runs on a machine, and whether the machine can run the device agent.
- Write IronFlockOS to a Drive: list the images and drives, and write IronFlockOS with a device’s
.flockfile. - Replace Linux with IronFlockOS: turn a running Linux machine into an IronFlockOS device.
- Update, Roll Back & Reset: keep an IronFlockOS device current, go back a release, or reset it.
- Appliance Commands: install, configure, update and look after an IronFlock appliance on a machine.