Iniciar sesión y gestionar dispositivos
Estos comandos hablan con una instancia de IronFlock, la nube o un appliance, en lugar de con la máquina en la que se ejecutan. ironflock login guarda una clave API en esta máquina, whoami nombra la cuenta a la que pertenece la clave y logout quita la clave. Después, ironflock device create, list y delete trabajan con los dispositivos de tus proyectos. agent install, os flash y os install pueden crear el dispositivo por ti con --project y --name.
Ninguno de ellos necesita root, y todos se ejecutan en Linux, macOS y Windows. Solo actúan en esta máquina: --host y --hosts se rechazan con el código de salida 2, y ni la clave ni el archivo de credenciales llegan nunca a otra máquina (Máquinas remotas por SSH).
login y whoami necesitan una instancia cuyo servicio de API responda a GET /v1/ironflock/whoami (Endpoints de la API). La nube de IronFlock lo hace. Una instancia sin esa ruta responde 404, y los comandos lo indican. Un appliance de IronFlock ofrece la ruta en cuanto ejecuta el servicio de API de IronFlock; las versiones del appliance que todavía no lo ejecutan no se pueden usar con estos comandos. Los comandos hablan con la API de la instancia y con nada más, y usan el proxy del entorno (HTTPS_PROXY, NO_PROXY) como cualquier otra solicitud de ironflock.
La instancia
La nube es la opción predeterminada. --instance, o si no la variable de entorno IRONFLOCK_INSTANCE, nombra otra instancia: un appliance. Indica lo que tengas a mano, y el comando deduce de ello la dirección de la API:
| Indicas | La API es |
|---|---|
nada, o ironflock.com, studio.ironflock.com o api.ironflock.com | https://api.ironflock.com |
el dominio del appliance, factory.example.com | https://api.factory.example.com |
la dirección con la que se abre Studio, https://factory.example.com/projects/12 | https://api.factory.example.com |
el propio host de la API, api.factory.example.com | https://api.factory.example.com |
Sin esquema, se entiende https://. http sin cifrar solo se acepta para una dirección de loopback, para un stack en esta máquina. Una dirección IP distinta de la de loopback se rechaza: a la API de un appliance se llega por su nombre. Un appliance en modo HTTP sin cifrar no tiene api.<domain>, y login no llega a él. El certificado de la instancia se comprueba con el almacén de confianza de esta máquina y con las autoridades de certificación de --ca-cert (un archivo PEM, varias veces para varias), por ejemplo la CA de tu empresa que firmó el certificado de un appliance. Nada desactiva la comprobación.
El archivo de credenciales
login guarda la clave en credentials.json, en la carpeta ironflock de la carpeta de configuración de tu usuario: ~/.config/ironflock/ en Linux, ~/Library/Application Support/ironflock/ en un Mac y %LOCALAPPDATA%\ironflock\credentials\ en Windows. Contiene una entrada por instancia y solo tú puedes leerlo. Un archivo o una carpeta que otros pueden leer o cambiar no se usa: el comando termina con el código de salida 3, dice cómo repararlo y no cambia nada.
Para scripts y CI, IRONFLOCK_API_KEY contiene una clave que todos los comandos usan en lugar de la guardada. login nunca la lee ni la guarda.
| Variable | Significado |
|---|---|
IRONFLOCK_INSTANCE | La instancia cuando no se indica --instance |
IRONFLOCK_API_KEY | La clave API que se usa en lugar de la guardada |
HTTPS_PROXY, NO_PROXY | El proxy para las solicitudes a la instancia |
ironflock login
Guarda una clave API para una instancia, después de preguntar a la instancia de quién es la clave.
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.Se ejecuta en: Linux, macOS y Windows. Root: no es necesario. Pregunta: nada.
| Flag | Significado |
|---|---|
--key-file <file> | El archivo o la tubería que contiene la clave. Predeterminado: la entrada estándar, cuando no es una terminal |
--instance <instance> | La instancia. Predeterminado: IRONFLOCK_INSTANCE, si no la nube |
--ca-cert <file> | Una autoridad de certificación en la que confiar además de las de esta máquina; varias veces para varias |
- La clave nunca va en una línea de comandos. Viene de un archivo o de una tubería, y el comando nunca la pide en la terminal. Sin ninguno de los dos termina con el código de salida 2 y dice cómo pasarla. Los espacios en blanco alrededor de la clave se descartan. Una clave tiene 40 caracteres
0-9ya-f; cualquier otra cosa se rechaza antes de cualquier solicitud, y el error no la repite. - Antes de guardar nada, se pregunta a la instancia de quién es la clave. Una clave que la instancia no acepta, una instancia que no puede responder, un certificado que no es de confianza o una instancia a la que no se llega terminan con el código de salida 1, y lo que se había guardado antes queda como estaba.
- Un inicio de sesión en una instancia que ya tiene uno lo reemplaza. Los inicios de sesión de otras instancias se mantienen.
- La solicitud no sigue ninguna redirección, para que la clave no vaya a ningún otro host.
- Con
--json, el resultado es un objeto conaction(logged_in),instance,account_id,username,scopes,restrictionycredential_file.
Pon la clave en un archivo que solo tú puedas leer y luego inicia sesión:
(umask 077; cat > key.txt)
ironflock login --key-file key.txtEscribe o pega la clave en la terminal después de cat > key.txt, termina con Ctrl-D y elimina key.txt cuando login haya guardado la clave.
ironflock whoami
Nombra la cuenta a la que pertenece la clave y muestra lo que la clave puede hacer.
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 UTCLa clave es IRONFLOCK_API_KEY cuando está definida, si no la que login guardó para la instancia. Sin ninguna de las dos, el comando termina con el código de salida 3 y nombra el login que hay que ejecutar. Scopes son los permisos de la clave, none cuando no tiene ninguno. Restriction es none: everything the account may do, the projects 3, 5 o the app 5. Con --json, el resultado tiene instance, account_id, username, scopes, restriction, key_source (environment o credential_file) y, para una clave guardada, logged_in_at.
Una clave guardada que la instancia ya no acepta, por ejemplo una eliminada en Studio, no se quita: el error nombra el login que la reemplaza.
ironflock logout
Quita la clave guardada de una instancia. Los inicios de sesión de otras instancias se mantienen.
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 no habla con ninguna instancia: la clave sigue siendo válida hasta que la eliminas en Studio. No tener ningún inicio de sesión guardado no es un error: el comando lo dice y termina con el código de salida 0. Con IRONFLOCK_API_KEY definida, una nota dice que los comandos siguen usando la variable.
ironflock device create
Crea un dispositivo en un proyecto y escribe el archivo .flock del dispositivo, que contiene sus credenciales.
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.Se ejecuta en: Linux, macOS y Windows. Root: no es necesario. Necesita: una clave con el permiso devices:write; un proyecto indicado por nombre se busca con devices:read.
| Flag | Significado |
|---|---|
--project <project> | Obligatorio. La clave del proyecto, o su nombre |
--name <name> | Obligatorio. El nombre del dispositivo: de 1 a 100 letras, dígitos, puntos, guiones bajos y guiones. El proyecto no debe tener todavía un dispositivo con ese nombre |
-o, --output <file> | Obligatorio. El archivo para el .flock, con nombre *.flock, o - para la salida estándar |
--description <text> | Como máximo 2000 caracteres |
--wifi-ssid <name> | La red Wi-Fi del dispositivo. Va con --wifi-password-file |
--wifi-password-file <file> | El archivo o la tubería con la contraseña de la red. Va con --wifi-ssid |
--force | Reemplazar el archivo de -o cuando existe |
--instance, --ca-cert | Como en whoami |
- Un proyecto indicado por nombre se busca entre los proyectos en los que puede trabajar la clave, y debe ser exactamente el nombre de un proyecto. Un nombre que no es de ninguno da el código de salida 1. Un nombre que es de varios proyectos da el código de salida 2, y el mensaje nombra sus claves.
- El archivo
.flockes privado desde su primer byte: modo 0600, o en Windows una lista de acceso que solo te da acceso a ti. Un archivo existente no se reemplaza sin--force, y la carpeta y el nombre se comprueban antes de crear el dispositivo, porque la API devuelve las credenciales solo cuando se crea el dispositivo. En un sistema de archivos sin modos de archivo, como una memoria USB formateada en FAT, el archivo no es privado: escríbelo en un disco de la máquina y cópialo desde allí. -o -escribe el archivo en la salida estándar, que no debe ser una terminal, por ejemplo para enviarlo por una tubería a otra máquina. La línea del resultado va entonces a la salida de error estándar.- No se imprime nada del archivo: el resultado nombra el dispositivo por su clave y su nombre, y el proyecto.
- Si algo falla después de crear el dispositivo, el error lo dice y nombra el comando que elimina el dispositivo.
Conecta una máquina con el archivo como se describe en Comandos del agente del dispositivo, o escríbelo en una unidad con os flash.
ironflock device list
Lista los dispositivos sobre los que tiene derechos tu cuenta, dentro de los proyectos en los que puede actuar la clave.
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 -Necesita: una clave con el permiso devices:read. --project se queda con los dispositivos de un proyecto. No tener ningún dispositivo no es un error: el comando dice No devices. Con --json, el resultado tiene instance y devices, cada dispositivo con device_key, name, project_key, description, status, architecture y agent_version. Solo se leen estos campos de la respuesta: las credenciales de un dispositivo nunca están entre ellos.
ironflock device delete
Elimina un dispositivo de un proyecto. Un dispositivo eliminado no se puede recuperar.
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.Necesita: una clave con el permiso devices:write. La clave del dispositivo es el único argumento. El comando dice qué se elimina y pregunta, con No preseleccionado; --yes responde que sí. Sin terminal, y con --json, no pregunta nada y termina con el código de salida 4 salvo que se indique --yes: en ese caso no se elimina nada. Un dispositivo que no está en el proyecto, o que la clave no puede ver, da 404.
Instalar un dispositivo nuevo con --project y --name
ironflock agent install, ironflock os flash e ironflock os install aceptan --project <project> --name <name> en lugar de -c <device.flock>. El comando crea el dispositivo y continúa con el .flock que envía la plataforma, exactamente igual que continúa con el archivo de -c. El .flock se mantiene en memoria y en ningún archivo del que tengas que ocuparte.
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 | Significado |
|---|---|
--project <project> | El proyecto en el que crear el dispositivo: su clave o su nombre, como en device create |
--name <name> | El nombre del nuevo dispositivo, como en device create |
--instance <instance> | La instancia, como en whoami |
--ca-cert <file> | agent install: una autoridad de certificación del certificado de la instancia. os flash y os install tienen un --ca-cert propio, para el dispositivo; con --project también se confía en él para la instancia |
--wait-online[=<duration>] | Solo os install con --host: después del comando allí, esperar hasta la duración indicada (de 1 minuto a 2 horas; sin valor, 15 minutos) a que la plataforma vea el dispositivo en línea. El valor va tras =, como en --wait-online=20m |
--projecty--namevan juntos y excluyen-c.agent installyos flashnecesitan una de las dos opciones;os installsin ninguna usa el.flockdel agente instalado, como antes.--dry-runcon--projectse rechaza, porque una ejecución de prueba no crea nada.- La clave es la de
whoami:IRONFLOCK_API_KEY, si no el inicio de sesión guardado. Un comando ejecutado consudose ejecuta como root y busca el inicio de sesión de root: pasa la clave consudo --preserve-env=IRONFLOCK_API_KEY, o ejecuta el comando desde tu propia máquina con--host. Con--host, a la plataforma se le pregunta desde tu máquina, y la máquina recibe solo el.flock: la clave, el archivo de credenciales eIRONFLOCK_API_KEYnunca llegan a ella. - La plataforma entrega el
.flockde un dispositivo solo en la respuesta que lo crea. Por eso, un nombre que el proyecto ya tiene se rechaza (código de salida 1): instala ese dispositivo con su.flocky-c, o elimínalo antes condevice delete. - Si un paso falla después de crear el dispositivo, el error lo dice y nombra el comando
device deleteque quita el dispositivo. Ejecútalo y luego vuelve a ejecutar el mismo comando.
Errores
Un fallo termina con el código de salida 1 y una frase. La frase de la instancia va después del estado.
| Respuesta | La frase dice |
|---|---|
| No se llega, certificado no de confianza | No se puede llegar a la instancia, con una indicación para --ca-cert |
400 | La instancia rechazó la solicitud, y por qué |
401 | La instancia no acepta la clave, y de dónde vino. Para una clave guardada, el login que la reemplaza |
403 | La clave no puede hacer esto: sus permisos, o los proyectos o la app a los que está limitada, no lo permiten. whoami los muestra |
404 | Para delete: el dispositivo no está en el proyecto, o la clave no puede verlo. Para create: el proyecto no existe para esta clave |
409 | Un conflicto con lo que tiene la plataforma, como un nombre de dispositivo que el proyecto ya tiene |
500, 503, 504 | La plataforma no está disponible. Para create y delete, también que el cambio puede haberse hecho, y el device list que lo muestra |
Tras cualquier fallo una vez escrita la solicitud, y tras Ctrl-C mientras create o delete espera, el mensaje dice que el cambio puede haberse hecho. Ejecuta ironflock device list antes de repetirlo: un segundo create con el mismo nombre es un conflicto, y la API no vuelve a devolver las credenciales del primer dispositivo (Studio puede descargar su archivo de configuración).
Códigos de salida
Estos comandos usan los códigos de salida de todos los comandos.
| Código | Significa aquí |
|---|---|
| 0 | Hecho |
| 1 | La instancia o la plataforma rechazó o falló, un nombre de proyecto no es de ninguno, o no se pudo escribir un archivo |
| 2 | La línea de comandos es incorrecta: un flag que falta o es incorrecto, un nombre de proyecto que es de varios proyectos, un archivo existente sin --force, --host o --hosts. No se preguntó a la plataforma |
| 3 | Sin inicio de sesión: IRONFLOCK_API_KEY no está definida y no hay ninguno guardado; o no se puede usar el archivo de credenciales. No se preguntó a la plataforma |
| 4 | La pregunta de device delete se respondió con no, o no se pudo hacer y no se indicó --yes. No se eliminó nada |
| 130 | Interrumpido mientras se preguntaba a la plataforma. El cambio puede haberse hecho |