Skip to Content
IoT App DevelopmentIronFlock CLILog In & Manage Devices

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 giveThe API is
nothing, or ironflock.com, studio.ironflock.com or api.ironflock.comhttps://api.ironflock.com
the appliance’s domain, factory.example.comhttps://api.factory.example.com
the address Studio is opened with, https://factory.example.com/projects/12https://api.factory.example.com
the API’s own host, api.factory.example.comhttps://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.

VariableMeaning
IRONFLOCK_INSTANCEThe instance when --instance is not given
IRONFLOCK_API_KEYThe API key to use instead of the stored one
HTTPS_PROXY, NO_PROXYThe 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.

FlagMeaning
--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-9 and a-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 --json the result is one object with action (logged_in), instance, account_id, username, scopes, restriction and credential_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.txt

Type 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 UTC

The 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.

FlagMeaning
--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
--forceReplace the file of -o when it exists
--instance, --ca-certAs 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 .flock file 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
FlagMeaning
--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
  • --project and --name go together and exclude -c. agent install and os flash need one of the two; os install without either takes the installed agent’s .flock, as before. --dry-run with --project is refused, because a dry run creates nothing.
  • The key is the one of whoami: IRONFLOCK_API_KEY, else the stored login. A command run with sudo runs as root and looks for root’s login: pass the key with sudo --preserve-env=IRONFLOCK_API_KEY, or run the command from your own machine with --host. With --host the platform is asked from your machine, and the machine gets the .flock alone: the key, the credential file and IRONFLOCK_API_KEY never reach it.
  • The platform gives a device’s .flock only in the answer that creates it. A name the project has already is therefore refused (exit code 1): install that device with its .flock and -c, or delete it first with device delete.
  • If a step fails after the device was made, the error says so and names the device delete command 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.

AnswerThe sentence says
Not reached, certificate not trustedThe instance cannot be reached, with a hint for --ca-cert
400The instance refused the request, and why
401The instance does not take the key, and where it came from. For a stored key, the login that replaces it
403The key may not do this: its scopes, or the projects or the app it is limited to, do not allow it. whoami shows them
404For delete: the device is not in the project, or the key cannot see it. For create: the project does not exist for this key
409A conflict with what the platform holds, such as a device name that the project has already
500, 503, 504The 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.

CodeMeans here
0Done
1The instance or the platform refused or failed, a project name is none, or a file could not be written
2The 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
3No login: IRONFLOCK_API_KEY is not set and none is stored; or the credential file cannot be used. The platform was not asked
4The question of device delete was answered with no, or could not be asked and --yes was not given. Nothing was deleted
130Interrupted while the platform was asked. The change may have been made
Last updated on