Skip to Content
Desarrollo de apps IoTIronFlock CLIIniciar sesión y gestionar dispositivos

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:

IndicasLa API es
nada, o ironflock.com, studio.ironflock.com o api.ironflock.comhttps://api.ironflock.com
el dominio del appliance, factory.example.comhttps://api.factory.example.com
la dirección con la que se abre Studio, https://factory.example.com/projects/12https://api.factory.example.com
el propio host de la API, api.factory.example.comhttps://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.

VariableSignificado
IRONFLOCK_INSTANCELa instancia cuando no se indica --instance
IRONFLOCK_API_KEYLa clave API que se usa en lugar de la guardada
HTTPS_PROXY, NO_PROXYEl 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.

FlagSignificado
--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-9 y a-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 con action (logged_in), instance, account_id, username, scopes, restriction y credential_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.txt

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

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

FlagSignificado
--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
--forceReemplazar el archivo de -o cuando existe
--instance, --ca-certComo 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 .flock es 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
FlagSignificado
--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
  • --project y --name van juntos y excluyen -c. agent install y os flash necesitan una de las dos opciones; os install sin ninguna usa el .flock del agente instalado, como antes. --dry-run con --project se 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 con sudo se ejecuta como root y busca el inicio de sesión de root: pasa la clave con sudo --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 e IRONFLOCK_API_KEY nunca llegan a ella.
  • La plataforma entrega el .flock de 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 .flock y -c, o elimínalo antes con device delete.
  • Si un paso falla después de crear el dispositivo, el error lo dice y nombra el comando device delete que 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.

RespuestaLa frase dice
No se llega, certificado no de confianzaNo se puede llegar a la instancia, con una indicación para --ca-cert
400La instancia rechazó la solicitud, y por qué
401La instancia no acepta la clave, y de dónde vino. Para una clave guardada, el login que la reemplaza
403La clave no puede hacer esto: sus permisos, o los proyectos o la app a los que está limitada, no lo permiten. whoami los muestra
404Para delete: el dispositivo no está en el proyecto, o la clave no puede verlo. Para create: el proyecto no existe para esta clave
409Un conflicto con lo que tiene la plataforma, como un nombre de dispositivo que el proyecto ya tiene
500, 503, 504La 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ódigoSignifica aquí
0Hecho
1La instancia o la plataforma rechazó o falló, un nombre de proyecto no es de ninguno, o no se pudo escribir un archivo
2La 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
3Sin 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
4La pregunta de device delete se respondió con no, o no se pudo hacer y no se indicó --yes. No se eliminó nada
130Interrumpido mientras se preguntaba a la plataforma. El cambio puede haberse hecho
Last updated on