Skip to Content
IoT-App-EntwicklungIronFlock CLIAnmelden & Geräte verwalten

Anmelden & Geräte verwalten

Diese Befehle sprechen mit einer IronFlock-Instanz, der Cloud oder einer Appliance, statt mit der Maschine, auf der sie laufen. ironflock login speichert einen API-Key auf dieser Maschine, whoami nennt das Konto, dem der Key gehört, und logout entfernt den Key. ironflock device create, list und delete arbeiten dann mit den Geräten Ihrer Projekte. agent install, os flash und os install können das Gerät mit --project und --name für Sie erstellen.

Keiner davon braucht root, und alle laufen unter Linux, macOS und Windows. Sie wirken nur auf dieser Maschine: --host und --hosts werden mit Exit-Code 2 abgelehnt, und weder der Key noch die Anmeldedatei gehen je an eine andere Maschine (Entfernte Maschinen über SSH).

login und whoami brauchen eine Instanz, deren API-Service GET /v1/ironflock/whoami beantwortet (API-Endpunkte). Die IronFlock-Cloud tut das. Eine Instanz ohne diese Route antwortet mit 404, und die Befehle sagen das. Eine IronFlock-Appliance bietet die Route an, sobald sie den IronFlock-API-Service ausführt; Appliance-Releases, die ihn noch nicht ausführen, können mit diesen Befehlen nicht verwendet werden. Die Befehle sprechen mit der API der Instanz und mit nichts anderem und verwenden den Proxy der Umgebung (HTTPS_PROXY, NO_PROXY) wie jede andere Anfrage von ironflock.

Die Instanz

Die Cloud ist der Standard. --instance, sonst die Umgebungsvariable IRONFLOCK_INSTANCE, nennt eine andere Instanz: eine Appliance. Geben Sie an, was Sie zur Hand haben, und der Befehl leitet daraus die Adresse der API ab:

Sie geben anDie API ist
nichts, oder ironflock.com, studio.ironflock.com oder api.ironflock.comhttps://api.ironflock.com
die Domain der Appliance, factory.example.comhttps://api.factory.example.com
die Adresse, mit der Studio geöffnet wird, https://factory.example.com/projects/12https://api.factory.example.com
den eigenen Host der API, api.factory.example.comhttps://api.factory.example.com

Ohne Schema ist https:// gemeint. Einfaches http wird nur für eine Loopback-Adresse angenommen, für einen Stack auf dieser Maschine. Eine andere IP-Adresse als die Loopback-Adresse wird abgelehnt: Die API einer Appliance wird über ihren Namen erreicht. Eine Appliance im einfachen HTTP-Modus hat kein api.<domain>, und login erreicht sie nicht. Das Zertifikat der Instanz wird gegen den Vertrauensspeicher dieser Maschine und die Zertifizierungsstellen von --ca-cert geprüft (eine PEM-Datei, mehrfach für mehrere), zum Beispiel die CA Ihres Unternehmens, die das Zertifikat einer Appliance signiert hat. Nichts schaltet die Prüfung ab.

Die Anmeldedatei

login bewahrt den Key in credentials.json im Ordner ironflock des Konfigurationsordners Ihres Benutzers auf: ~/.config/ironflock/ unter Linux, ~/Library/Application Support/ironflock/ auf einem Mac und %LOCALAPPDATA%\ironflock\credentials\ unter Windows. Sie enthält einen Eintrag pro Instanz und ist nur für Sie lesbar. Eine Datei oder ein Ordner, den andere lesen oder ändern können, wird nicht verwendet: Der Befehl endet mit Exit-Code 3, sagt, wie man das behebt, und ändert nichts.

Für Skripte und CI enthält IRONFLOCK_API_KEY einen Key, den jeder Befehl statt des gespeicherten verwendet. login liest oder speichert ihn nie.

VariableBedeutung
IRONFLOCK_INSTANCEDie Instanz, wenn --instance nicht angegeben ist
IRONFLOCK_API_KEYDer API-Key, der statt des gespeicherten verwendet wird
HTTPS_PROXY, NO_PROXYDer Proxy für die Anfragen an die Instanz

ironflock login

Speichert einen API-Key für eine Instanz, nachdem die Instanz gefragt wurde, wem der Key gehört.

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.

Läuft unter: Linux, macOS und Windows. Root-Rechte: nicht nötig. Fragt: nichts.

FlagBedeutung
--key-file <file>Die Datei oder Pipe, die den Key enthält. Standard: die Standardeingabe, wenn sie kein Terminal ist
--instance <instance>Die Instanz. Standard: IRONFLOCK_INSTANCE, sonst die Cloud
--ca-cert <file>Eine Zertifizierungsstelle, der zusätzlich zu denen dieser Maschine vertraut wird; mehrfach für mehrere
  • Der Key steht nie in einer Befehlszeile. Er kommt aus einer Datei oder einer Pipe, und der Befehl fragt nie im Terminal danach. Ohne eines davon endet er mit Exit-Code 2 und sagt, wie man einen übergibt. Leerraum um den Key wird entfernt. Ein Key besteht aus 40 Zeichen 0-9 und a-f; alles andere wird vor jeder Anfrage abgelehnt, und der Fehler wiederholt ihn nicht.
  • Bevor etwas gespeichert wird, wird die Instanz gefragt, wem der Key gehört. Ein Key, den die Instanz nicht annimmt, eine Instanz, die nicht antworten kann, ein nicht vertrauenswürdiges Zertifikat oder eine Instanz, die nicht erreicht wird, endet mit Exit-Code 1, und was vorher gespeichert war, bleibt, wie es war.
  • Eine Anmeldung bei einer Instanz, die schon eine hat, ersetzt sie. Die Anmeldungen anderer Instanzen bleiben.
  • Die Anfrage folgt keiner Weiterleitung, damit der Key an keinen anderen Host geht.
  • Mit --json ist das Ergebnis ein Objekt mit action (logged_in), instance, account_id, username, scopes, restriction und credential_file.

Legen Sie den Key in eine Datei, die nur Sie lesen können, und melden Sie sich dann an:

(umask 077; cat > key.txt) ironflock login --key-file key.txt

Tippen oder fügen Sie den Key nach cat > key.txt im Terminal ein, beenden Sie mit Strg+D, und löschen Sie key.txt, sobald login den Key gespeichert hat.

ironflock whoami

Nennt das Konto, dem der Key gehört, und zeigt, was der Key darf.

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

Der Key ist IRONFLOCK_API_KEY, wenn die Variable gesetzt ist, sonst der, den login für die Instanz gespeichert hat. Ohne beides endet der Befehl mit Exit-Code 3 und nennt das login, das auszuführen ist. Scopes sind die Berechtigungen des Keys, none, wenn er keine hat. Restriction ist none: everything the account may do, the projects 3, 5 oder the app 5. Mit --json hat das Ergebnis instance, account_id, username, scopes, restriction, key_source (environment oder credential_file) und, für einen gespeicherten Key, logged_in_at.

Ein gespeicherter Key, den die Instanz nicht mehr annimmt, zum Beispiel einer, der in Studio gelöscht wurde, wird nicht entfernt: Der Fehler nennt das login, das ihn ersetzt.

ironflock logout

Entfernt den gespeicherten Key einer Instanz. Die Anmeldungen anderer Instanzen bleiben.

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 spricht mit keiner Instanz: Der Key bleibt gültig, bis Sie ihn in Studio löschen. Keine gespeicherte Anmeldung ist kein Fehler: Der Befehl sagt das und endet mit Exit-Code 0. Ist IRONFLOCK_API_KEY gesetzt, sagt ein Hinweis, dass die Befehle weiterhin die Variable verwenden.

ironflock device create

Erstellt ein Gerät in einem Projekt und schreibt die .flock-Datei des Geräts, die die Zugangsdaten des Geräts enthält.

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.

Läuft unter: Linux, macOS und Windows. Root-Rechte: nicht nötig. Braucht: einen Key mit der Berechtigung devices:write; ein per Name angegebenes Projekt wird mit devices:read nachgeschlagen.

FlagBedeutung
--project <project>Pflicht. Der Key des Projekts oder sein Name
--name <name>Pflicht. Der Name des Geräts: 1 bis 100 Buchstaben, Ziffern, Punkte, Unterstriche und Bindestriche. Das Projekt darf noch kein Gerät mit diesem Namen haben
-o, --output <file>Pflicht. Die Datei für die .flock, mit dem Namen *.flock, oder - für die Standardausgabe
--description <text>Höchstens 2000 Zeichen
--wifi-ssid <name>Das WLAN des Geräts. Gehört zu --wifi-password-file
--wifi-password-file <file>Die Datei oder Pipe mit der Passphrase des Netzes. Gehört zu --wifi-ssid
--forceDie Datei von -o ersetzen, wenn sie existiert
--instance, --ca-certWie bei whoami
  • Ein per Name angegebenes Projekt wird in den Projekten gesucht, in denen der Key arbeiten kann, und muss genau der Name eines Projekts sein. Ein Name, der zu keinem gehört, ergibt Exit-Code 1. Ein Name, der zu mehreren Projekten gehört, ergibt Exit-Code 2, und die Meldung nennt ihre Keys.
  • Die .flock-Datei ist vom ersten Byte an privat: Modus 0600, oder unter Windows eine Zugriffsliste, die nur Ihnen Zugriff gewährt. Eine existierende Datei wird ohne --force nicht ersetzt, und Ordner und Name werden geprüft, bevor das Gerät erstellt wird, denn die API gibt die Zugangsdaten nur zurück, wenn das Gerät erstellt wird. Auf einem Dateisystem ohne Dateimodi, etwa einem FAT-formatierten USB-Stick, ist die Datei nicht privat: Schreiben Sie sie auf eine Festplatte der Maschine und kopieren Sie sie von dort.
  • -o - schreibt die Datei auf die Standardausgabe, die kein Terminal sein darf, zum Beispiel um sie per Pipe an eine andere Maschine zu leiten. Die Ergebniszeile geht dann auf die Standardfehlerausgabe.
  • Nichts aus der Datei wird ausgegeben: Das Ergebnis nennt das Gerät mit Key und Name sowie das Projekt.
  • Schlägt etwas fehl, nachdem das Gerät erstellt wurde, sagt der Fehler das und nennt den Befehl, der das Gerät löscht.

Verbinden Sie eine Maschine mit der Datei wie unter Befehle für den Geräte-Agenten beschrieben, oder schreiben Sie sie mit os flash auf ein Laufwerk.

ironflock device list

Listet die Geräte auf, für die Ihr Konto Rechte hat, in den Projekten, in denen der Key handeln darf.

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 -

Braucht: einen Key mit der Berechtigung devices:read. --project behält die Geräte eines Projekts. Kein Gerät ist kein Fehler: Der Befehl sagt No devices. Mit --json hat das Ergebnis instance und devices, jedes Gerät mit device_key, name, project_key, description, status, architecture und agent_version. Nur diese Felder werden aus der Antwort gelesen: Die Zugangsdaten eines Geräts sind nie darunter.

ironflock device delete

Löscht ein Gerät aus einem Projekt. Ein gelöschtes Gerät lässt sich nicht zurückholen.

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.

Braucht: einen Key mit der Berechtigung devices:write. Der Key des Geräts ist das eine Argument. Der Befehl sagt, was wegfällt, und fragt, mit Nein vorausgewählt; --yes antwortet mit Ja. Ohne Terminal und mit --json fragt er nichts und endet mit Exit-Code 4, außer --yes ist angegeben: Dann wird nichts gelöscht. Ein Gerät, das nicht im Projekt ist oder das der Key nicht sehen kann, ergibt 404.

Ein neues Gerät mit --project und --name installieren

ironflock agent install, ironflock os flash und ironflock os install nehmen --project <project> --name <name> anstelle von -c <device.flock>. Der Befehl erstellt das Gerät und macht mit der .flock weiter, die die Plattform sendet, genau so, wie er mit der Datei von -c weitermacht. Die .flock wird im Speicher gehalten und in keiner Datei, um die Sie sich kümmern müssen.

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
FlagBedeutung
--project <project>Das Projekt, in dem das Gerät erstellt wird: sein Key oder sein Name, wie bei device create
--name <name>Der Name des neuen Geräts, wie bei device create
--instance <instance>Die Instanz, wie bei whoami
--ca-cert <file>agent install: eine Zertifizierungsstelle des Zertifikats der Instanz. os flash und os install haben ein eigenes --ca-cert für das Gerät; mit --project wird ihm auch für die Instanz vertraut
--wait-online[=<duration>]Nur os install über --host: nach dem Befehl dort bis zur angegebenen Dauer (1 Minute bis 2 Stunden; allein 15 Minuten) warten, bis die Plattform das Gerät online sieht. Der Wert folgt auf =, wie in --wait-online=20m
  • --project und --name gehören zusammen und schließen -c aus. agent install und os flash brauchen eines von beidem; os install ohne beides nimmt die .flock des installierten Agenten, wie bisher. --dry-run mit --project wird abgelehnt, weil ein Probelauf nichts erstellt.
  • Der Key ist der von whoami: IRONFLOCK_API_KEY, sonst die gespeicherte Anmeldung. Ein mit sudo ausgeführter Befehl läuft als root und sucht nach der Anmeldung von root: Übergeben Sie den Key mit sudo --preserve-env=IRONFLOCK_API_KEY, oder führen Sie den Befehl von Ihrer eigenen Maschine aus mit --host aus. Mit --host wird die Plattform von Ihrer Maschine aus gefragt, und die Maschine erhält nur die .flock: Der Key, die Anmeldedatei und IRONFLOCK_API_KEY erreichen sie nie.
  • Die Plattform gibt die .flock eines Geräts nur in der Antwort heraus, die es erstellt. Ein Name, den das Projekt schon hat, wird daher abgelehnt (Exit-Code 1): Installieren Sie dieses Gerät mit seiner .flock und -c, oder löschen Sie es zuerst mit device delete.
  • Schlägt ein Schritt fehl, nachdem das Gerät erstellt wurde, sagt der Fehler das und nennt den Befehl device delete, der das Gerät entfernt. Führen Sie diesen aus, dann noch einmal denselben Befehl.

Fehler

Ein Fehlschlag endet mit Exit-Code 1 und einem Satz. Der Satz der Instanz folgt auf den Status.

AntwortDer Satz sagt
Nicht erreicht, Zertifikat nicht vertrauenswürdigDie Instanz ist nicht erreichbar, mit einem Hinweis auf --ca-cert
400Die Instanz hat die Anfrage abgelehnt, und warum
401Die Instanz nimmt den Key nicht an, und woher er kam. Für einen gespeicherten Key das login, das ihn ersetzt
403Der Key darf das nicht: Seine Berechtigungen oder die Projekte oder die App, auf die er beschränkt ist, erlauben es nicht. whoami zeigt sie
404Bei delete: Das Gerät ist nicht im Projekt, oder der Key kann es nicht sehen. Bei create: Das Projekt existiert für diesen Key nicht
409Ein Konflikt mit dem, was die Plattform hat, etwa ein Gerätename, den das Projekt schon hat
500, 503, 504Die Plattform ist nicht verfügbar. Bei create und delete auch, dass die Änderung vorgenommen worden sein kann, und das device list, das es zeigt

Nach jedem Fehlschlag, nachdem die Anfrage geschrieben wurde, und nach Strg+C, während create oder delete wartet, sagt die Meldung, dass die Änderung vorgenommen worden sein kann. Führen Sie ironflock device list aus, bevor Sie sie wiederholen: Ein zweites create mit demselben Namen ist ein Konflikt, und die API gibt die Zugangsdaten des ersten Geräts nicht noch einmal zurück (Studio kann seine Konfigurationsdatei herunterladen).

Exit-Codes

Diese Befehle verwenden die Exit-Codes jedes Befehls.

CodeBedeutet hier
0Erledigt
1Die Instanz oder die Plattform hat abgelehnt oder ist fehlgeschlagen, ein Projektname gehört zu keinem Projekt, oder eine Datei konnte nicht geschrieben werden
2Die Befehlszeile ist falsch: ein fehlendes oder falsches Flag, ein Projektname, der zu mehreren Projekten gehört, eine existierende Datei ohne --force, --host oder --hosts. Die Plattform wurde nicht gefragt
3Keine Anmeldung: IRONFLOCK_API_KEY ist nicht gesetzt und keine gespeichert; oder die Anmeldedatei kann nicht verwendet werden. Die Plattform wurde nicht gefragt
4Die Frage von device delete wurde mit Nein beantwortet oder konnte nicht gestellt werden, und --yes war nicht angegeben. Nichts wurde gelöscht
130Unterbrochen, während die Plattform gefragt wurde. Die Änderung kann vorgenommen worden sein
Last updated on