Skip to Content
Desenvolvimento de Apps IoTIronFlock CLILogin e gerenciamento de dispositivos

Login e gerenciamento de dispositivos

Estes comandos falam com uma instância IronFlock, a nuvem ou um appliance, em vez de com a máquina em que rodam. ironflock login guarda uma chave de API nesta máquina, whoami indica a conta a que a chave pertence, e logout remove a chave. ironflock device create, list e delete trabalham então com os dispositivos dos seus projetos. agent install, os flash e os install podem criar o dispositivo para você com --project e --name.

Nenhum deles precisa de root, e todos rodam no Linux, no macOS e no Windows. Eles agem apenas nesta máquina: --host e --hosts são recusados com o código de saída 2, e nem a chave nem o arquivo de credenciais vão jamais para outra máquina (Máquinas remotas via SSH).

login e whoami precisam de uma instância cujo serviço de API responda a GET /v1/ironflock/whoami (Endpoints da API). A nuvem IronFlock responde. Uma instância sem essa rota responde 404, e os comandos dizem isso. Um appliance IronFlock oferece a rota assim que roda o serviço IronFlock API; releases do appliance que ainda não o rodam não podem ser usadas com estes comandos. Os comandos falam com a API da instância e com nada mais, e usam o proxy do ambiente (HTTPS_PROXY, NO_PROXY) como qualquer outra requisição do ironflock.

A instância

A nuvem é o padrão. --instance, ou então a variável de ambiente IRONFLOCK_INSTANCE, indica outra instância: um appliance. Informe o que você tiver à mão, e o comando deduz dele o endereço da API:

Você informaA API é
nada, ou ironflock.com, studio.ironflock.com ou api.ironflock.comhttps://api.ironflock.com
o domínio do appliance, factory.example.comhttps://api.factory.example.com
o endereço com que o Studio é aberto, https://factory.example.com/projects/12https://api.factory.example.com
o próprio host da API, api.factory.example.comhttps://api.factory.example.com

Sem esquema, entende-se https://. http simples só é aceito para um endereço de loopback, para uma stack nesta máquina. Um endereço IP que não seja o de loopback é recusado: a API de um appliance é acessada pelo nome. Um appliance no modo HTTP simples não tem api.<domain>, e o login não o alcança. O certificado da instância é verificado com o repositório de confiança desta máquina e com as autoridades certificadoras de --ca-cert (um arquivo PEM, mais de uma vez para várias), por exemplo a CA da sua empresa que assinou o certificado de um appliance. Nada desativa a verificação.

O arquivo de credenciais

O login guarda a chave em credentials.json, na pasta ironflock da pasta de configuração do seu usuário: ~/.config/ironflock/ no Linux, ~/Library/Application Support/ironflock/ em um Mac e %LOCALAPPDATA%\ironflock\credentials\ no Windows. Ele contém uma entrada por instância e só você pode lê-lo. Um arquivo ou uma pasta que outros podem ler ou alterar não é usado: o comando termina com o código de saída 3, diz como repará-lo e não altera nada.

Para scripts e CI, IRONFLOCK_API_KEY contém uma chave que todo comando usa no lugar da guardada. O login nunca a lê nem a guarda.

VariávelSignificado
IRONFLOCK_INSTANCEA instância quando --instance não é informado
IRONFLOCK_API_KEYA chave de API a usar no lugar da guardada
HTTPS_PROXY, NO_PROXYO proxy para as requisições à instância

ironflock login

Guarda uma chave de API para uma instância, depois de perguntar à instância de quem é a chave.

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.

Roda em: Linux, macOS e Windows. Root: não necessário. Pergunta: nada.

FlagSignificado
--key-file <file>O arquivo ou pipe que contém a chave. Padrão: a entrada padrão, quando ela não é um terminal
--instance <instance>A instância. Padrão: IRONFLOCK_INSTANCE, senão a nuvem
--ca-cert <file>Uma autoridade certificadora em que confiar além das desta máquina; mais de uma vez para várias
  • A chave nunca vai para uma linha de comando. Ela vem de um arquivo ou de um pipe, e o comando nunca a pede no terminal. Sem um dos dois, ele termina com o código de saída 2 e diz como passá-la. Espaços em branco em volta da chave são descartados. Uma chave tem 40 caracteres 0-9 e a-f; qualquer outra coisa é recusada antes de qualquer requisição, e o erro não a repete.
  • Antes que algo seja guardado, a instância é consultada sobre de quem é a chave. Uma chave que a instância não aceita, uma instância que não consegue responder, um certificado não confiável ou uma instância que não é alcançada termina com o código de saída 1, e o que estava guardado antes continua como estava.
  • Um login em uma instância que já tem um o substitui. Os logins de outras instâncias permanecem.
  • A requisição não segue nenhum redirecionamento, para que a chave não vá para nenhum outro host.
  • Com --json, o resultado é um objeto com action (logged_in), instance, account_id, username, scopes, restriction e credential_file.

Coloque a chave em um arquivo que só você pode ler e depois faça login:

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

Digite ou cole a chave no terminal depois de cat > key.txt, termine com Ctrl-D e exclua key.txt quando o login tiver guardado a chave.

ironflock whoami

Indica a conta a que a chave pertence e mostra o que a chave pode fazer.

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

A chave é IRONFLOCK_API_KEY quando ela está definida, senão a que o login guardou para a instância. Sem nenhuma das duas, o comando termina com o código de saída 3 e indica o login a executar. Scopes são as permissões da chave, none quando ela não tem nenhuma. Restriction é none: everything the account may do, the projects 3, 5 ou the app 5. Com --json, o resultado tem instance, account_id, username, scopes, restriction, key_source (environment ou credential_file) e, para uma chave guardada, logged_in_at.

Uma chave guardada que a instância não aceita mais, por exemplo uma excluída no Studio, não é removida: o erro indica o login que a substitui.

ironflock logout

Remove a chave guardada de uma instância. Os logins de outras instâncias permanecem.

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.

O logout não fala com nenhuma instância: a chave continua válida até você excluí-la no Studio. Não haver login guardado não é erro: o comando diz isso e termina com o código de saída 0. Com IRONFLOCK_API_KEY definida, uma nota diz que os comandos continuam usando a variável.

ironflock device create

Cria um dispositivo em um projeto e escreve o arquivo .flock do dispositivo, que contém as credenciais do dispositivo.

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.

Roda em: Linux, macOS e Windows. Root: não necessário. Precisa de: uma chave com a permissão devices:write; um projeto informado pelo nome é procurado com devices:read.

FlagSignificado
--project <project>Obrigatório. A chave do projeto, ou o seu nome
--name <name>Obrigatório. O nome do dispositivo: de 1 a 100 letras, dígitos, pontos, sublinhados e hífens. O projeto ainda não pode ter um dispositivo com esse nome
-o, --output <file>Obrigatório. O arquivo para o .flock, com nome *.flock, ou - para a saída padrão
--description <text>No máximo 2000 caracteres
--wifi-ssid <name>A rede Wi-Fi do dispositivo. Vai junto com --wifi-password-file
--wifi-password-file <file>O arquivo ou pipe com a senha da rede. Vai junto com --wifi-ssid
--forceSubstitui o arquivo de -o quando ele existe
--instance, --ca-certComo para whoami
  • Um projeto informado pelo nome é procurado entre os projetos em que a chave pode trabalhar, e precisa ser exatamente o nome de um projeto. Um nome que não é de nenhum dá o código de saída 1. Um nome que é de vários projetos dá o código de saída 2, e a mensagem indica as chaves deles.
  • O arquivo .flock é privado desde o primeiro byte: modo 0600 ou, no Windows, uma lista de acesso que concede acesso só a você. Um arquivo que existe não é substituído sem --force, e a pasta e o nome são verificados antes de o dispositivo ser criado, porque a API retorna as credenciais apenas quando o dispositivo é criado. Em um sistema de arquivos sem modos de arquivo, como um pen drive formatado em FAT, o arquivo não é privado: escreva-o em um disco da máquina e copie-o de lá.
  • -o - escreve o arquivo na saída padrão, que não pode ser um terminal, por exemplo para passá-lo por pipe a outra máquina. A linha de resultado vai então para o erro padrão.
  • Nada do arquivo é impresso: o resultado indica o dispositivo pela chave e pelo nome, e o projeto.
  • Se algo falhar depois de o dispositivo ter sido criado, o erro diz isso e indica o comando que exclui o dispositivo.

Conecte uma máquina com o arquivo como descrito em Comandos do agente do dispositivo, ou grave-o em uma unidade com os flash.

ironflock device list

Lista os dispositivos para os quais a sua conta tem direitos, nos projetos em que a chave pode agir.

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 -

Precisa de: uma chave com a permissão devices:read. --project mantém os dispositivos de um projeto. Nenhum dispositivo não é erro: o comando diz No devices. Com --json, o resultado tem instance e devices, cada dispositivo com device_key, name, project_key, description, status, architecture e agent_version. Apenas esses campos são lidos da resposta: as credenciais de um dispositivo nunca estão entre eles.

ironflock device delete

Exclui um dispositivo de um projeto. Um dispositivo excluído não pode ser recuperado.

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.

Precisa de: uma chave com a permissão devices:write. A chave do dispositivo é o único argumento. O comando diz o que será removido e pergunta, com Não pré-selecionado; --yes responde sim. Sem terminal, e com --json, ele não pergunta nada e termina com o código de saída 4, a menos que --yes seja informado: nada é excluído então. Um dispositivo que não está no projeto, ou que a chave não pode ver, dá 404.

Instalar um novo dispositivo com --project e --name

ironflock agent install, ironflock os flash e ironflock os install aceitam --project <project> --name <name> no lugar de -c <device.flock>. O comando cria o dispositivo e continua com o .flock que a plataforma envia, exatamente como continua com o arquivo de -c. O .flock é mantido na memória e em nenhum arquivo de que você precise cuidar.

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>O projeto em que criar o dispositivo: a sua chave ou o seu nome, como para device create
--name <name>O nome do novo dispositivo, como para device create
--instance <instance>A instância, como para whoami
--ca-cert <file>agent install: uma autoridade certificadora do certificado da instância. os flash e os install têm um --ca-cert próprio, para o dispositivo; com --project, ele também é confiável para a instância
--wait-online[=<duration>]Somente os install via --host: depois do comando lá, espera até a duração (de 1 minuto a 2 horas; sozinho, 15 minutos) para a plataforma ver o dispositivo online. O valor vem depois de =, como em --wait-online=20m
  • --project e --name vão juntos e excluem -c. agent install e os flash precisam de uma das duas formas; os install sem nenhuma usa o .flock do agente instalado, como antes. --dry-run com --project é recusado, porque uma simulação não cria nada.
  • A chave é a do whoami: IRONFLOCK_API_KEY, senão o login guardado. Um comando executado com sudo roda como root e procura o login do root: passe a chave com sudo --preserve-env=IRONFLOCK_API_KEY, ou execute o comando a partir da sua própria máquina com --host. Com --host, a plataforma é consultada a partir da sua máquina, e a máquina recebe apenas o .flock: a chave, o arquivo de credenciais e IRONFLOCK_API_KEY nunca chegam a ela.
  • A plataforma fornece o .flock de um dispositivo apenas na resposta que o cria. Por isso, um nome que o projeto já tem é recusado (código de saída 1): instale esse dispositivo com o seu .flock e -c, ou exclua-o antes com device delete.
  • Se uma etapa falhar depois de o dispositivo ter sido criado, o erro diz isso e indica o comando device delete que remove o dispositivo. Execute-o e depois o mesmo comando de novo.

Erros

Uma falha termina com o código de saída 1 e uma frase. A frase da instância vem depois do status.

RespostaA frase diz
Não alcançada, certificado não confiávelA instância não pode ser alcançada, com uma dica para --ca-cert
400A instância recusou a requisição, e por quê
401A instância não aceita a chave, e de onde ela veio. Para uma chave guardada, o login que a substitui
403A chave não pode fazer isso: as suas permissões, ou os projetos ou o app a que ela está limitada, não o permitem. O whoami os mostra
404Para delete: o dispositivo não está no projeto, ou a chave não pode vê-lo. Para create: o projeto não existe para esta chave
409Um conflito com o que a plataforma contém, como um nome de dispositivo que o projeto já tem
500, 503, 504A plataforma não está disponível. Para create e delete, também que a alteração pode ter sido feita, e o device list que o mostra

Depois de qualquer falha ocorrida com a requisição já enviada, e depois de Ctrl-C enquanto create ou delete espera, a mensagem diz que a alteração pode ter sido feita. Execute ironflock device list antes de repeti-la: um segundo create com o mesmo nome é um conflito, e a API não retorna de novo as credenciais do primeiro dispositivo (o Studio pode baixar o seu arquivo de configuração).

Códigos de saída

Estes comandos usam os códigos de saída de todos os comandos.

CódigoSignifica aqui
0Concluído
1A instância ou a plataforma recusou ou falhou, um nome de projeto não é de nenhum projeto, ou um arquivo não pôde ser escrito
2A linha de comando está errada: uma flag ausente ou errada, um nome de projeto que é de vários projetos, um arquivo existente sem --force, --host ou --hosts. A plataforma não foi consultada
3Nenhum login: IRONFLOCK_API_KEY não está definida e nenhum está guardado; ou o arquivo de credenciais não pode ser usado. A plataforma não foi consultada
4A pergunta do device delete foi respondida com não, ou não pôde ser feita e --yes não foi informado. Nada foi excluído
130Interrompido enquanto a plataforma era consultada. A alteração pode ter sido feita
Last updated on