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ê informa | A API é |
|---|---|
nada, ou ironflock.com, studio.ironflock.com ou api.ironflock.com | https://api.ironflock.com |
o domínio do appliance, factory.example.com | https://api.factory.example.com |
o endereço com que o Studio é aberto, https://factory.example.com/projects/12 | https://api.factory.example.com |
o próprio host da API, api.factory.example.com | https://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ável | Significado |
|---|---|
IRONFLOCK_INSTANCE | A instância quando --instance não é informado |
IRONFLOCK_API_KEY | A chave de API a usar no lugar da guardada |
HTTPS_PROXY, NO_PROXY | O 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.
| Flag | Significado |
|---|---|
--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-9ea-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 comaction(logged_in),instance,account_id,username,scopes,restrictionecredential_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.txtDigite 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 UTCA 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.
| Flag | Significado |
|---|---|
--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 |
--force | Substitui o arquivo de -o quando ele existe |
--instance, --ca-cert | Como 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| Flag | Significado |
|---|---|
--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 |
--projecte--namevão juntos e excluem-c.agent installeos flashprecisam de uma das duas formas;os installsem nenhuma usa o.flockdo agente instalado, como antes.--dry-runcom--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 comsudoroda como root e procura o login do root: passe a chave comsudo --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 eIRONFLOCK_API_KEYnunca chegam a ela. - A plataforma fornece o
.flockde 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.flocke-c, ou exclua-o antes comdevice delete. - Se uma etapa falhar depois de o dispositivo ter sido criado, o erro diz isso e indica o comando
device deleteque 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.
| Resposta | A frase diz |
|---|---|
| Não alcançada, certificado não confiável | A instância não pode ser alcançada, com uma dica para --ca-cert |
400 | A instância recusou a requisição, e por quê |
401 | A instância não aceita a chave, e de onde ela veio. Para uma chave guardada, o login que a substitui |
403 | A 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 |
404 | Para 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 |
409 | Um conflito com o que a plataforma contém, como um nome de dispositivo que o projeto já tem |
500, 503, 504 | A 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ódigo | Significa aqui |
|---|---|
| 0 | Concluído |
| 1 | A 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 |
| 2 | A 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 |
| 3 | Nenhum 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 |
| 4 | A 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 |
| 130 | Interrompido enquanto a plataforma era consultada. A alteração pode ter sido feita |