Log In & Manage Devices
These commands talk to an IronFlock instance, the cloud or an appliance, instead of to the machine they run on. ironflock login stores an API key on this machine, whoami names the account the key belongs to, and logout removes the key. ironflock device create, list and delete then work on the devices of your projects. agent install, os flash and os install can create the device for you with --project and --name.
None of them needs root, and all run on Linux, macOS and Windows. They act on this machine only: --host and --hosts are refused with exit code 2, and neither the key nor the credential file ever goes to another machine (Remote Machines over SSH).
login and whoami need an instance whose API service answers GET /v1/ironflock/whoami (API Endpoints). The IronFlock cloud does. An instance without that route answers 404, and the commands say so. An IronFlock appliance offers the route once it runs the IronFlock API service; appliance releases that do not run it yet cannot be used with these commands. The commands talk to the instance’s API and to nothing else, and use the proxy of the environment (HTTPS_PROXY, NO_PROXY) like every other request of ironflock.
The Instance
The cloud is the default. --instance, or else the environment variable IRONFLOCK_INSTANCE, names another instance: an appliance. Give what you have at hand, and the command derives the API’s address from it:
| You give | The API is |
|---|---|
nothing, or ironflock.com, studio.ironflock.com or api.ironflock.com | https://api.ironflock.com |
the appliance’s domain, factory.example.com | https://api.factory.example.com |
the address Studio is opened with, https://factory.example.com/projects/12 | https://api.factory.example.com |
the API’s own host, api.factory.example.com | https://api.factory.example.com |
Without a scheme, https:// is meant. Plain http is taken for a loopback address alone, for a stack on this machine. An IP address other than the loopback is refused: an appliance’s API is reached by its name. An appliance in plain HTTP mode has no api.<domain>, and login does not reach it. The instance’s certificate is checked against this machine’s trust store and the certificate authorities of --ca-cert (a PEM file, more than once for several), for example your company’s CA that signed an appliance’s certificate. Nothing turns the check off.
The Credential File
login keeps the key in credentials.json in the folder ironflock of your user’s configuration folder: ~/.config/ironflock/ on Linux, ~/Library/Application Support/ironflock/ on a Mac and %LOCALAPPDATA%\ironflock\credentials\ on Windows. It holds one entry per instance and is readable by you alone. A file or folder that others can read or change is not used: the command ends with exit code 3, says how to repair it and changes nothing.
For scripts and CI, IRONFLOCK_API_KEY holds a key that every command takes instead of the stored one. login never reads or stores it.
| Variable | Meaning |
|---|---|
IRONFLOCK_INSTANCE | The instance when --instance is not given |
IRONFLOCK_API_KEY | The API key to use instead of the stored one |
HTTPS_PROXY, NO_PROXY | The proxy for the requests to the instance |
ironflock login
Stores an API key for an instance, after asking the instance whose key it is.
ironflock login [--key-file <file>] [--instance <domain or URL>] [--ca-cert <file>]...$ ironflock login --key-file key.txt --instance factory.example.com
Logged in to https://api.factory.example.com as operator (account 12). The key is stored in /home/operator/.config/ironflock/credentials.json.Runs on: Linux, macOS and Windows. Root: not needed. Asks: nothing.
| Flag | Meaning |
|---|---|
--key-file <file> | The file or pipe that holds the key. Default: standard input, when that is not a terminal |
--instance <instance> | The instance. Default: IRONFLOCK_INSTANCE, else the cloud |
--ca-cert <file> | A certificate authority to trust besides this machine’s; more than once for several |
- The key never goes on a command line. It comes from a file or a pipe, and the command never asks for it at the terminal. Without one it ends with exit code 2 and says how to pass one. White space around the key is dropped. A key is 40 characters
0-9anda-f; anything else is refused before any request, and the error does not repeat it. - Before anything is stored, the instance is asked whose the key is. A key the instance does not take, an instance that cannot answer, an untrusted certificate or an instance that is not reached ends with exit code 1, and what was stored before stays as it was.
- A login to an instance that has one replaces it. The logins of other instances stay.
- The request follows no redirect, so that the key goes to no other host.
- With
--jsonthe result is one object withaction(logged_in),instance,account_id,username,scopes,restrictionandcredential_file.
Put the key into a file that only you can read, then log in:
(umask 077; cat > key.txt)
ironflock login --key-file key.txtType or paste the key into the terminal after cat > key.txt, end with Ctrl-D, and delete key.txt when login has stored the key.
ironflock whoami
Names the account the key belongs to, and shows what the key may do.
ironflock whoami [--instance <domain or URL>] [--ca-cert <file>]...$ ironflock whoami --instance factory.example.com
Instance: https://api.factory.example.com
Account: operator (12)
Scopes: devices:read, devices:write
Restriction: the projects 3
Key: stored by 'ironflock login' on 2026-11-19 10:00 UTCThe key is IRONFLOCK_API_KEY when it is set, else the one login stored for the instance. Without either, the command ends with exit code 3 and names the login to run. Scopes are the key’s scopes, none when it has no scope. Restriction is none: everything the account may do, the projects 3, 5 or the app 5. With --json the result has instance, account_id, username, scopes, restriction, key_source (environment or credential_file) and, for a stored key, logged_in_at.
A stored key that the instance no longer takes, for example one deleted in Studio, is not removed: the error names the login that replaces it.
ironflock logout
Removes the stored key of an instance. The logins of other instances stay.
ironflock logout [--instance <domain or URL>]$ ironflock logout --instance factory.example.com
Logged out of https://api.factory.example.com: its key is removed from /home/operator/.config/ironflock/credentials.json. The key itself stays valid until it is deleted in Studio.logout talks to no instance: the key stays valid until you delete it in Studio. No stored login is no error: the command says so and ends with exit code 0. With IRONFLOCK_API_KEY set, a note says that the commands still use the variable.
ironflock device create
Creates a device in a project and writes the device’s .flock file, which holds the device’s credentials.
ironflock device create --project <project> --name <name> -o <file.flock> [flags]$ ironflock device create --project 12 --name press-7 -o press-7.flock
Created the device press-7 (key 345) in the project Packaging (key 12). Its .flock is in press-7.flock: it holds the device's credentials, which the platform shows no more. 'sudo ironflock agent install -c press-7.flock' connects a machine as this device.Runs on: Linux, macOS and Windows. Root: not needed. Needs: a key with the scope devices:write; a project given by name is looked up with devices:read.
| Flag | Meaning |
|---|---|
--project <project> | Required. The project’s key, or its name |
--name <name> | Required. The device’s name: 1 to 100 letters, digits, dots, underscores and hyphens. The project must not have a device of that name yet |
-o, --output <file> | Required. The file for the .flock, named *.flock, or - for standard output |
--description <text> | At most 2000 characters |
--wifi-ssid <name> | The Wi-Fi network of the device. Goes with --wifi-password-file |
--wifi-password-file <file> | The file or pipe with the network’s passphrase. Goes with --wifi-ssid |
--force | Replace the file of -o when it exists |
--instance, --ca-cert | As for whoami |
- A project given by name is looked up in the projects the key can work in, and must be exactly one project’s name. A name that is none is exit code 1. A name that is several projects’ is exit code 2, and the message names their keys.
- The
.flockfile is private from its first byte: mode 0600, or on Windows an access list that grants you alone. A file that exists is not replaced without--force, and the folder and name are checked before the device is made, because the API returns the credentials only when the device is made. On a file system without file modes, such as a USB stick formatted FAT, the file is not private: write it to a disk of the machine and copy it from there. -o -writes the file to standard output, which must not be a terminal, for example to pipe it to another machine. The result line then goes to standard error.- Nothing of the file is printed: the result names the device by key and name, and the project.
- If something fails after the device was made, the error says so and names the command that deletes the device.
Connect a machine with the file as described in Device Agent Commands, or write it onto a drive with os flash.
ironflock device list
Lists the devices your account has rights for, in the projects the key may act in.
ironflock device list [--project <project>] [--instance <instance>] [--ca-cert <file>]...$ ironflock device list --project Packaging
KEY NAME PROJECT STATUS ARCHITECTURE AGENT
17 press-7 12 CONNECTED amd64 1.4.2
18 press-8 12 CONFIGURING amd64 -Needs: a key with the scope devices:read. --project keeps one project’s devices. No device is no error: the command says No devices. With --json the result has instance and devices, each device with device_key, name, project_key, description, status, architecture and agent_version. Only these fields are read from the answer: a device’s credentials are never among them.
ironflock device delete
Deletes a device from a project. A deleted device cannot be brought back.
ironflock device delete --project <project> <device_key> [--yes] [--instance <instance>] [--ca-cert <file>]...$ ironflock device delete --project Packaging 17
This deletes the device 17 from the project Packaging (key 12) of https://api.ironflock.com. A deleted device cannot be brought back.
Delete the device 17? [y/N]
Deleted the device press-7 (key 17) from the project 12.Needs: a key with the scope devices:write. The device’s key is the one argument. The command says what goes and asks, with No preselected; --yes answers yes. Without a terminal, and with --json, it asks nothing and ends with exit code 4 unless --yes is given: nothing is deleted then. A device that is not in the project, or that the key cannot see, is a 404.
Install a New Device with --project and --name
ironflock agent install, ironflock os flash and ironflock os install take --project <project> --name <name> in place of -c <device.flock>. The command creates the device and goes on with the .flock the platform sends, exactly as it goes on with the file of -c. The .flock is kept in memory and in no file you have to look after.
sudo ironflock agent install --project Packaging --name press-9 --yes
ironflock os flash --project 12 --name cell-4 -d /dev/sdb
ironflock --host admin@machine os install --project 12 --name cell-4 --disk /dev/sda --yes --wait-online| Flag | Meaning |
|---|---|
--project <project> | The project to create the device in: its key or its name, as for device create |
--name <name> | The new device’s name, as for device create |
--instance <instance> | The instance, as for whoami |
--ca-cert <file> | agent install: a certificate authority of the instance’s certificate. os flash and os install have a --ca-cert of their own, for the device; with --project it is trusted for the instance as well |
--wait-online[=<duration>] | os install over --host only: after the command there, wait up to the duration (1 minute to 2 hours; alone 15 minutes) for the platform to see the device online. The value follows =, as in --wait-online=20m |
--projectand--namego together and exclude-c.agent installandos flashneed one of the two;os installwithout either takes the installed agent’s.flock, as before.--dry-runwith--projectis refused, because a dry run creates nothing.- The key is the one of
whoami:IRONFLOCK_API_KEY, else the stored login. A command run withsudoruns as root and looks for root’s login: pass the key withsudo --preserve-env=IRONFLOCK_API_KEY, or run the command from your own machine with--host. With--hostthe platform is asked from your machine, and the machine gets the.flockalone: the key, the credential file andIRONFLOCK_API_KEYnever reach it. - The platform gives a device’s
.flockonly in the answer that creates it. A name the project has already is therefore refused (exit code 1): install that device with its.flockand-c, or delete it first withdevice delete. - If a step fails after the device was made, the error says so and names the
device deletecommand that removes the device. Run that, then the same command again.
Errors
A failure ends with exit code 1 and a sentence. The instance’s sentence follows the status.
| Answer | The sentence says |
|---|---|
| Not reached, certificate not trusted | The instance cannot be reached, with a hint for --ca-cert |
400 | The instance refused the request, and why |
401 | The instance does not take the key, and where it came from. For a stored key, the login that replaces it |
403 | The key may not do this: its scopes, or the projects or the app it is limited to, do not allow it. whoami shows them |
404 | For delete: the device is not in the project, or the key cannot see it. For create: the project does not exist for this key |
409 | A conflict with what the platform holds, such as a device name that the project has already |
500, 503, 504 | The platform is not available. For create and delete, also that the change may have been made, and the device list that shows |
After any failure once the request was written, and after Ctrl-C while create or delete waits, the message says that the change may have been made. Run ironflock device list before you repeat it: a second create of the same name is a conflict, and the API does not return the first device’s credentials again (Studio can download its configuration file).
Exit Codes
These commands use the exit codes of every command.
| Code | Means here |
|---|---|
| 0 | Done |
| 1 | The instance or the platform refused or failed, a project name is none, or a file could not be written |
| 2 | The command line is wrong: a missing or wrong flag, a project name that is several projects’, an existing file without --force, --host or --hosts. The platform was not asked |
| 3 | No login: IRONFLOCK_API_KEY is not set and none is stored; or the credential file cannot be used. The platform was not asked |
| 4 | The question of device delete was answered with no, or could not be asked and --yes was not given. Nothing was deleted |
| 130 | Interrupted while the platform was asked. The change may have been made |