Skip to Content
IoT アプリ開発IronFlock CLIログインとデバイスの管理

ログインとデバイスの管理

これらのコマンドは、実行するマシンではなく、IronFlock インスタンス(クラウドまたはアプライアンス)と通信します。ironflock login はこのマシンに API キー を保存し、whoami はキーが属するアカウントを示し、logout はキーを削除します。その後、ironflock device create、list、delete で、プロジェクトのデバイスを操作します。agent install、os flash、os install は、--project と --name を使ってデバイスを作成することもできます。

どのコマンドも root は不要で、すべて Linux、macOS、Windows で動作します。これらはこのマシン上でだけ動作します。--host と --hosts は終了コード 2 で拒否され、キーも認証情報ファイルも、別のマシンに送られることはありません(SSH 経由のリモートマシン)。

login と whoami には、API サービスが GET /v1/ironflock/whoami に応答するインスタンスが必要です(API エンドポイント)。IronFlock クラウドは応答します。このルートを持たないインスタンスは 404 を返し、コマンドはその旨を表示します。IronFlock アプライアンスは、IronFlock API サービスを実行するようになると、このルートを提供します。まだこのサービスを実行していないアプライアンスのリリースでは、これらのコマンドは使えません。コマンドはインスタンスの API とだけ通信し、ironflock のほかのすべてのリクエストと同じく、環境のプロキシ(HTTPS_PROXY、NO_PROXY)を使います。

インスタンス

既定値はクラウドです。--instance、それがなければ環境変数 IRONFLOCK_INSTANCE で、別のインスタンス(アプライアンス)を指定します。手元にあるものを指定すれば、コマンドがそこから API のアドレスを導き出します:

指定するものAPI
何も指定しない、または ironflock.com、studio.ironflock.com、api.ironflock.comhttps://api.ironflock.com
アプライアンスのドメイン factory.example.comhttps://api.factory.example.com
Studio を開くアドレス https://factory.example.com/projects/12https://api.factory.example.com
API 自身のホスト api.factory.example.comhttps://api.factory.example.com

スキームがない場合は https:// とみなします。プレーンな http は、ループバックアドレス(このマシン上のスタック)に対してだけ受け付けます。ループバック以外の IP アドレスは拒否されます。アプライアンスの API には名前でアクセスします。プレーン HTTP モードのアプライアンスには api.<domain> がなく、login は到達できません。インスタンスの証明書は、このマシンのトラストストアと、--ca-cert の認証局(PEM ファイル。複数ある場合は複数回指定)に照らしてチェックされます。たとえば、アプライアンスの証明書に署名した自社の CA です。このチェックを無効にする方法はありません。

認証情報ファイル

login は、ユーザーの設定フォルダー内の ironflock フォルダーにある credentials.json にキーを保存します。Linux では ~/.config/ironflock/、Mac では ~/Library/Application Support/ironflock/、Windows では %LOCALAPPDATA%\ironflock\credentials\ です。このファイルはインスタンスごとに 1 つのエントリを持ち、あなただけが読めます。他人が読み取りや変更をできるファイルやフォルダーは使われません。その場合、コマンドは終了コード 3 で終了し、修復方法を示し、何も変更しません。

スクリプトや CI 向けには、IRONFLOCK_API_KEY に、すべてのコマンドが保存済みのキーの代わりに使うキーを設定できます。login がこの変数を読んだり保存したりすることはありません。

変数意味
IRONFLOCK_INSTANCE--instance を指定しない場合のインスタンス
IRONFLOCK_API_KEY保存済みのキーの代わりに使う API キー
HTTPS_PROXY、NO_PROXYインスタンスへのリクエストに使うプロキシ

ironflock login

キーが誰のものかをインスタンスに問い合わせたうえで、そのインスタンス用の API キーを保存します。

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.

動作環境: Linux、macOS、Windows。root: 不要。質問: なし。

フラグ意味
--key-file <file>キーを含むファイルまたはパイプ。既定値:端末でない場合の標準入力
--instance <instance>インスタンス。既定値:IRONFLOCK_INSTANCE、なければクラウド
--ca-cert <file>このマシンの認証局に加えて信頼する認証局。複数ある場合は複数回指定
  • キーがコマンドラインに載ることはありません。 キーはファイルまたはパイプから受け取り、コマンドが端末でキーを尋ねることはありません。どちらもない場合は終了コード 2 で終了し、キーの渡し方を示します。キーの前後の空白は取り除かれます。キーは 0-9 と a-f からなる 40 文字です。それ以外はリクエストの前に拒否され、エラーにキーが繰り返されることはありません。
  • 何かを保存する前に、キーが誰のものかをインスタンスに問い合わせます。インスタンスが受け付けないキー、応答できないインスタンス、信頼されていない証明書、到達できないインスタンスの場合は終了コード 1 で終了し、それまでに保存されていたものはそのまま残ります。
  • すでにログインがあるインスタンスへのログインは、それを置き換えます。 ほかのインスタンスのログインは残ります。
  • リクエストはリダイレクトに従いません。 キーがほかのホストに送られないようにするためです。
  • --json では、結果は action(logged_in)、instance、account_id、username、scopes、restriction、credential_file を持つ 1 つのオブジェクトです。

キーを自分だけが読めるファイルに保存してから、ログインします:

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

cat > key.txt の後に、ターミナルにキーを入力または貼り付けて Ctrl-D で終え、login がキーを保存したら key.txt を削除してください。

ironflock whoami

キーが属するアカウントを示し、キーで何ができるかを表示します。

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

キーは、IRONFLOCK_API_KEY が設定されていればそれ、なければ login がそのインスタンス用に保存したものです。どちらもない場合、コマンドは終了コード 3 で終了し、実行すべき login を示します。Scopes はキーの スコープ で、スコープがない場合は none です。Restriction は none: everything the account may do、the projects 3, 5、the app 5 のいずれかです。--json では、結果に instance、account_id、username、scopes、restriction、key_source(environment または credential_file)と、保存済みのキーの場合は logged_in_at が含まれます。

インスタンスが受け付けなくなった保存済みのキー(たとえば Studio で削除したキー)は削除されません。エラーには、それを置き換える login が示されます。

ironflock logout

インスタンスの保存済みのキーを削除します。ほかのインスタンスのログインは残ります。

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 はどのインスタンスとも通信しません。キーは、Studio で削除するまで有効なままです。保存済みのログインがなくてもエラーではありません。コマンドはその旨を表示し、終了コード 0 で終了します。IRONFLOCK_API_KEY が設定されている場合は、コマンドが引き続きこの変数を使うことを注記で示します。

ironflock device create

プロジェクトにデバイスを作成し、デバイスの認証情報を含むデバイスの .flock ファイルを書き込みます。

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.

動作環境: Linux、macOS、Windows。root: 不要。必要なもの: スコープ devices:write を持つキー。名前で指定したプロジェクトは devices:read で検索されます。

フラグ意味
--project <project>必須。プロジェクトのキーまたは名前
--name <name>必須。デバイスの名前。英字、数字、ドット、アンダースコア、ハイフンで 1~100 文字。プロジェクトに同じ名前のデバイスがまだないこと
-o, --output <file>必須。.flock を書き込むファイル(名前は *.flock)、または標準出力を表す -
--description <text>最大 2000 文字
--wifi-ssid <name>デバイスの Wi-Fi ネットワーク。--wifi-password-file と一緒に指定します
--wifi-password-file <file>ネットワークのパスフレーズを含むファイルまたはパイプ。--wifi-ssid と一緒に指定します
--force-o のファイルが存在する場合に置き換える
--instance, --ca-certwhoami と同じ
  • 名前で指定したプロジェクト は、キーが操作できるプロジェクトの中から検索され、ちょうど 1 つのプロジェクトの名前である必要があります。どのプロジェクトの名前でもない場合は終了コード 1 です。複数のプロジェクトの名前である場合は終了コード 2 で、メッセージにそれらのキーが示されます。
  • .flock ファイルは最初のバイトから非公開です。モード 0600、Windows ではあなただけにアクセスを許可するアクセスリストです。既存のファイルは --force なしでは置き換えられません。また、フォルダーと名前はデバイスを作成する前にチェックされます。API が認証情報を返すのは、デバイスを作成したときだけだからです。FAT でフォーマットした USB スティックなど、ファイルモードのないファイルシステムでは、ファイルは非公開になりません。マシンのディスクに書き込み、そこからコピーしてください。
  • -o - はファイルを標準出力に書き込みます。標準出力は端末であってはなりません。たとえば、ファイルをパイプで別のマシンに渡す場合に使います。このとき、結果の行は標準エラー出力に出力されます。
  • ファイルの内容は何も表示されません。結果には、デバイスのキーと名前、およびプロジェクトが示されます。
  • デバイスの作成後に何かが失敗した場合、エラーはその旨を示し、デバイスを削除するコマンドを示します。

このファイルでマシンを接続するには デバイスエージェントのコマンド の説明に従うか、os flash でドライブに書き込みます。

ironflock device list

アカウントが権限を持つデバイスを、キーが操作できるプロジェクトの範囲で一覧表示します。

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 -

必要なもの: スコープ devices:read を持つキー。--project を指定すると、1 つのプロジェクトのデバイスだけを表示します。デバイスがなくてもエラーではありません。コマンドは No devices. と表示します。--json では、結果に instance と devices が含まれ、各デバイスには device_key、name、project_key、description、status、architecture、agent_version があります。レスポンスから読み取るのはこれらのフィールドだけです。デバイスの認証情報がこれらに含まれることはありません。

ironflock device delete

プロジェクトからデバイスを削除します。削除したデバイスは元に戻せません。

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.

必要なもの: スコープ devices:write を持つキー。デバイスのキーが唯一の引数です。コマンドは何が削除されるかを示し、No を既定として質問します。--yes は yes と答えます。端末がない場合と --json では何も質問せず、--yes を指定しない限り終了コード 4 で終了します。このとき、何も削除されません。プロジェクトにないデバイス、またはキーから見えないデバイスは 404 です。

--project と --name で新しいデバイスをインストールする

ironflock agent install、ironflock os flash、ironflock os install は、-c <device.flock> の代わりに --project <project> --name <name> を受け付けます。コマンドはデバイスを作成し、プラットフォームが送る .flock を使って、-c のファイルの場合とまったく同じように処理を続けます。.flock はメモリ上に保持され、あなたが管理する必要のあるファイルには保存されません。

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
フラグ意味
--project <project>デバイスを作成するプロジェクト。device create と同じく、キーまたは名前
--name <name>新しいデバイスの名前。device create と同じ
--instance <instance>インスタンス。whoami と同じ
--ca-cert <file>agent install:インスタンスの証明書の認証局。os flash と os install には、デバイス用の独自の --ca-cert があります。--project と併用すると、それはインスタンスに対しても信頼されます
--wait-online[=<duration>]--host 経由の os install のみ:そこでのコマンドの後、プラットフォームがデバイスをオンラインと認識するまで、指定した時間(1 分~2 時間。値なしでは 15 分)待ちます。値は --wait-online=20m のように = の後に続けます
  • --project と --name は一緒に指定し、-c とは併用できません。agent install と os flash には、2 つのうちどちらかが必要です。os install は、どちらもない場合、従来どおりインストール済みのエージェントの .flock を使います。--project と --dry-run の併用は拒否されます。ドライランでは何も作成されないためです。
  • キーは whoami と同じです。IRONFLOCK_API_KEY、なければ保存済みのログインです。sudo で実行したコマンドは root として動作し、root のログインを探します。キーは sudo --preserve-env=IRONFLOCK_API_KEY で渡すか、自分のマシンから --host でコマンドを実行してください。--host では、プラットフォームへの問い合わせは自分のマシンから行われ、対象のマシンが受け取るのは .flock だけです。キー、認証情報ファイル、IRONFLOCK_API_KEY が対象のマシンに届くことはありません。
  • プラットフォームがデバイスの .flock を渡すのは、デバイスを作成する応答の中だけです。そのため、プロジェクトにすでにある名前は拒否されます(終了コード 1)。そのデバイスは、その .flock と -c でインストールするか、先に device delete で削除してください。
  • デバイスの作成後にいずれかの手順が失敗した場合、エラーはその旨を示し、デバイスを削除する device delete コマンドを示します。それを実行してから、同じコマンドをもう一度実行してください。

エラー

失敗すると、終了コード 1 と 1 つの文で終了します。インスタンスの文はステータスの後に続きます。

応答文の内容
到達できない、証明書が信頼されていないインスタンスに到達できないこと。--ca-cert のヒント付き
400インスタンスがリクエストを拒否したことと、その理由
401インスタンスがキーを受け付けないことと、キーの出どころ。保存済みのキーの場合は、それを置き換える login
403キーにはこの操作ができないこと。スコープ、またはキーが限定されているプロジェクトやアプリが許可していません。whoami でそれらを確認できます
404delete の場合:デバイスがプロジェクトにない、またはキーから見えない。create の場合:このキーにとってプロジェクトが存在しない
409プラットフォームが保持しているものとの競合。たとえば、プロジェクトにすでにあるデバイス名
500、503、504プラットフォームが利用できないこと。create と delete では、変更が行われた可能性があることと、それを確認する device list も示します

リクエストの書き込み後に失敗した場合、および create や delete の待機中に Ctrl-C を押した場合、メッセージは変更が行われた可能性があることを示します。繰り返す前に ironflock device list を実行してください。同じ名前での 2 回目の create は競合になり、API が最初のデバイスの認証情報を再度返すことはありません(Studio では設定ファイルをダウンロードできます)。

終了コード

これらのコマンドは、すべてのコマンドに共通する 終了コード を使います。

コードここでの意味
0完了
1インスタンスまたはプラットフォームが拒否した、または失敗した。プロジェクト名がどのプロジェクトの名前でもない。またはファイルを書き込めなかった
2コマンドラインの誤り:フラグがない、または誤っている、複数のプロジェクトの名前であるプロジェクト名、--force なしの既存ファイル、--host または --hosts。プラットフォームには問い合わせていません
3ログインがない:IRONFLOCK_API_KEY が設定されておらず、保存済みのログインもない。または認証情報ファイルが使えない。プラットフォームには問い合わせていません
4device delete の質問に no と答えた、または質問できず --yes が指定されていなかった。何も削除されていません
130プラットフォームへの問い合わせ中に中断された。変更が行われた可能性があります
Last updated on