Soracom

Users

開発者向け
フィードバック
Home 開発者向け SORACOM CLI 利用ガイド 応用的な使いかた

AI エージェントやスクリプトから利用する

soracom describe、--dry-run、SORACOM_JSON_ERRORS、soracom configure list の使いかたと、出力の絞り込みや認証情報の管理など、AI エージェントやスクリプトから SORACOM CLI を安全に利用する方法を説明します。

SORACOM CLI には、AI エージェントやスクリプトから soracom コマンドを実行するときに役立つ以下の機能があります。

soracom describe、--dry-run、SORACOM_JSON_ERRORS、soracom configure list は、SORACOM CLI v1.9.0 以降で利用できます。SORACOM CLI のアップデートについては、SORACOM CLI をアップデートする を参照してください。

コマンドの仕様を JSON で取得する

soracom describe を実行すると、コマンドとそのパラメーターを機械可読な JSON として出力できます。AI エージェントやスクリプトは、--help の出力 (テキスト) を解析しなくても、コマンドに指定できる値を調べられます。

soracom describe に指定する引数によって、出力される内容が異なります。

実行するコマンド出力される内容
soracom describeトップレベルのコマンドの一覧と、それぞれのサブコマンドの数
soracom describe --allすべてのコマンドの一覧 (API を呼び出すコマンドは、HTTP メソッドとパスを含む)
soracom describe {コマンドグループ}指定したコマンドグループに含まれるコマンドの一覧 (コマンド、HTTP メソッド、パス、概要)
soracom describe {コマンド}指定したコマンドのパラメーター、リクエストボディおよびレスポンスのスキーマ (型、必須かどうか、指定できる値など)

トップレベルのコマンドを一覧表示する 

$ soracom describe

[
  {
    "command": "analysis",
    "summary": "Manage database queries.",
    "commands": 3
  },
  :
]

コマンドグループに含まれるコマンドを一覧表示する

soracom sims に含まれるコマンドを一覧表示する例です。

$ soracom describe sims

[
  {
    "command": "sims activate",
    "method": "POST",
    "path": "/sims/{sim_id}/activate",
    "summary": "Activate SIM"
  },
  :
]

コマンドの仕様を表示する

soracom sims update-speed-class の仕様を表示する例です。

$ soracom describe sims update-speed-class

{
  "command": "sims update-speed-class",
  "method": "POST",
  "path": "/sims/{sim_id}/update_speed_class",
  "summary": "Updates the IoT SIM speed class",
  "description": "Updates the IoT SIM speed class.",
  "parameters": [
    {
      "name": "sim_id",
      "option": "sim-id",
      "in": "path",
      "type": "string",
      "required": true,
      "description": "SIM ID of the target SIM."
    }
  ],
  "requestBody": {
    "contentType": "application/json",
    "type": "object",
    "schema": "UpdateSpeedClassRequest",
    "required": ["speedClass"],
    "properties": [
      {
        "name": "speedClass",
        "option": "speed-class",
        "in": "body",
        "type": "string",
        "required": true,
        "description": "Speed class. ...",
        "enum": ["s1.minimum", "s1.slow", "s1.standard", "s1.fast", "s1.4xfast", "s1.8xfast", "u1.standard", "u1.slow"]
      }
    ]
  },
  "response": {
    "type": "object",
    "schema": "Sim",
    "fields": [
      :
    ]
  }
}

option は、soracom コマンドで指定するオプション名 (この例では --sim-id および --speed-class) です。enum には、指定できる値が出力されます。

送信される HTTP リクエストを事前に確認する

--dry-run フラグを指定すると、API を呼び出さずに、送信される予定の HTTP リクエスト (メソッド、URL、ヘッダー、ボディ) を JSON で出力します。ネットワーク経由の認証も行いません。設定の変更などの副作用を起こす前に、リクエストの内容を検証できます。--dry-run フラグは、すべてのコマンドに指定できます。

リクエストボディは、入力された内容がそのまま出力されます。パスワードや認証キーシークレット (authKey) などの機密情報が含まれることがあるため、--dry-run フラグを指定したときの出力の取り扱いには注意してください。

$ soracom sims update-speed-class --sim-id 8981100000000000000 --speed-class s1.4xfast --dry-run

{
  "body": {
    "speedClass": "s1.4xfast"
  },
  "dryRun": true,
  "headers": {
    "Content-Type": "application/json",
    "User-Agent": "soracom-cli/1.9.0",
    "X-Soracom-Lang": "en"
  },
  "method": "POST",
  "url": "https://api.soracom.io/v1/sims/8981100000000000000/update_speed_class"
}

X-Soracom-Api-Key や X-Soracom-Token などの秘匿ヘッダーおよびプロファイル由来のヘッダーの値は、<hidden> と出力されます。

エラーを JSON で出力する

SORACOM_JSON_ERRORS 環境変数に任意の値 (空文字列以外) を設定すると、エラーが JSON 形式で標準エラー出力に出力されます。SORACOM_JSON_ERRORS 環境変数を設定しない場合は、従来どおりテキスト形式で出力されます。

set SORACOM_JSON_ERRORS=1

$env:SORACOM_JSON_ERRORS = "1"

export SORACOM_JSON_ERRORS=1

出力されるエラーの形式は、以下のとおりです。

  • API がエラーを返した場合は、API から返されたエラー (JSON) がそのまま出力されます。

    {"code":"AGW0011", "message":"Invalid API Key or Token"}

  • それ以外のエラー (存在しないサブコマンドを指定した場合など) は、error オブジェクトの message にエラーメッセージを含む JSON で出力されます。

    たとえば、存在しないサブコマンドを指定した場合、SORACOM_JSON_ERRORS 環境変数を設定していないと、エラーメッセージに続けてコマンドの使いかた (Usage) が人間向けのテキストで出力されます。

    $ soracom sims foo

    Error: unknown command "foo" for "soracom sims"
Usage:
  soracom sims [flags]
  soracom sims [command]

Available Commands:
  :

    SORACOM_JSON_ERRORS 環境変数を設定すると、エラーメッセージだけが JSON で出力されます。

    $ SORACOM_JSON_ERRORS=1 soracom sims foo

    {"error":{"message":"unknown command \"foo\" for \"soracom sims\""}}
存在しないサブコマンドを指定した場合の終了コード

soracom sims foo のように存在しないサブコマンドを指定すると、SORACOM CLI は 0 以外の終了コードで終了します。SORACOM_JSON_ERRORS 環境変数の設定には影響されません。スクリプトでは、終了コードでコマンドの成否を判定できます。

プロファイルの名前を一覧表示する

soracom configure list を実行すると、設定済みの プロファイル の名前が JSON 配列で出力されます。プロファイルの内容 (認証情報) は出力されません。プロファイルが 1 つもない場合は、[] が出力されます。

$ soracom configure list

[
  "default",
  "prod"
]

プロファイルのファイルには、暗号化されていない認証情報が含まれていることがあります。AI エージェントやスクリプトで利用できるプロファイルを調べるときは、プロファイルのファイルを直接読まずに、soracom configure list を使用してください。なお、soracom configure get を実行すると認証情報が出力されます。

AI エージェントで利用するときのヒント

ここでは、SORACOM CLI v1.9.0 より前のバージョンでも利用できる機能を使って、AI エージェントから SORACOM CLI を安全かつ効率よく利用するためのヒントを紹介します。

出力を必要な情報に絞り込む

コマンドの出力が大きいと、AI エージェントが一度に扱える情報量を圧迫します。AI エージェントには、必要な情報だけを渡してください。

  • 配列を返すコマンドの一部では、--jsonl を指定すると、配列の要素を 1 行に 1 つずつ出力します (JSON Lines 形式)。
  • --fetch-all を指定すると、すべてのページの結果をまとめて取得します。詳しくは、大量のデータを取得する (ページング) を参照してください。

--fetch-all を指定すると、出力が非常に大きくなることがあります。jq や head などのコマンドに出力を渡して、必要な項目や件数に絞り込んでください。以下は、すべての IoT SIM の SIM ID と状態だけを出力する例です。

$ soracom sims list --fetch-all --jsonl | jq -c '{simId, status}'

--jsonl および --fetch-all を指定できるかどうかは、コマンドによって異なります。実行するコマンドの --help で確認してください。v1.9.0 以降では、soracom describe {コマンド} でも確認できます。

権限を絞った SAM ユーザーの認証キーを利用する

AI エージェントは、プロンプトインジェクションなどによって意図しないコマンドを実行することがあります。AI エージェントには、ルートユーザーの認証キーではなく、作業に必要な権限だけを設定した SAM ユーザーの認証キーを利用させてください。SAM ユーザーの作成と権限の設定については、SAM ユーザーを作成する および SAM ユーザーの権限を設定する を参照してください。

また、SORACOM_PROFILE_DIR 環境変数を設定すると、プロファイル を保存するディレクトリを変更できます。デフォルトは、macOS / Linux では ${HOME}/.soracom/、Windows では %HOMEPATH%\.soracom\ です。AI エージェント用のプロファイルだけを保存した専用のディレクトリを指定すると、AI エージェントが実行する SORACOM CLI は、そのディレクトリのプロファイルだけを利用します。

以下は、専用のディレクトリに AI エージェント用のプロファイル (agent) を作成する例です。

set SORACOM_PROFILE_DIR=%USERPROFILE%\.soracom-agent
soracom configure --profile agent

$env:SORACOM_PROFILE_DIR = "$env:USERPROFILE\.soracom-agent"
soracom configure --profile agent

export SORACOM_PROFILE_DIR=$HOME/.soracom-agent
soracom configure --profile agent

SORACOM_PROFILE_DIR 環境変数で指定したディレクトリに、agent.json が作成されます。AI エージェントを実行するときも、同じ SORACOM_PROFILE_DIR 環境変数を設定してください。

soracom configure で作成したプロファイルのファイルには、認証情報が暗号化されずに保存されます。認証情報をプロファイルのファイルに保存したくない場合は、認証情報をファイルやコマンドラインに記載しない を参照してください。

認証情報をファイルやコマンドラインに記載しない

プロファイルに profileCommand を指定すると、SORACOM CLI は指定したコマンドを実行し、そのコマンドが標準出力に出力した JSON から認証情報を読み込みます。認証情報をパスワードマネージャーなどで管理し、コマンドで取り出すようにすると、暗号化されていない認証情報をプロファイルのファイルに保存せずに SORACOM CLI を利用できます。

以下は、カバレッジタイプと profileCommand だけを記載したプロファイル (agent) を利用する例です。

  1. プロファイルを保存するディレクトリに、以下の内容の agent.json を作成します。

    {
  "coverageType": "jp",
  "profileCommand": "/path/to/print-credentials.sh"
}
    • coverageType: 日本カバレッジの場合は jp、グローバルカバレッジの場合は g を指定します。
    • profileCommand: 認証情報を出力するコマンドを指定します。

    プロファイルを保存するディレクトリのデフォルトは、macOS / Linux では ${HOME}/.soracom/、Windows では %HOMEPATH%\.soracom\ です。SORACOM_PROFILE_DIR 環境変数を設定している場合は、そのディレクトリに作成してください。詳しくは、権限を絞った SAM ユーザーの認証キーを利用する を参照してください。

    macOS / Linux では、所有者だけが agent.json を読み書きできるように設定してください (例: chmod 600 agent.json)。所有者以外にも読み取りなどが許可されているプロファイルを指定すると、SORACOM CLI はエラーを返します。

  2. --profile agent を指定してコマンドを実行します。

    $ soracom sims list --profile agent

    /path/to/print-credentials.sh が実行され、その出力に含まれる認証情報で認証します。接続先のカバレッジタイプには、agent.json の coverageType が利用されます。

profileCommand に指定したコマンドは、以下のような JSON を標準出力に出力するように作成してください。

{"authKeyId": "keyId-xxx", "authKey": "secret-xxx"}

コマンドの出力のうち、SORACOM CLI が認証に利用するのは以下の項目だけです。コマンドは、いずれか 1 つの組み合わせだけを出力してください。複数の組み合わせを出力した場合は、表の上にある組み合わせが優先されます。優先された組み合わせで認証に失敗しても、ほかの組み合わせは利用されません。coverageType、sandbox、endpoint などをコマンドの出力に含めても利用されません。

認証に利用するものコマンドが出力する項目
認証キーauthKeyId、authKey
SAM ユーザーのユーザー名とパスワードoperatorId、username、password
ルートユーザーのメールアドレスとパスワードemail、password

指定したコマンドは、シェルを経由せずに直接実行されます。パイプ (|)、リダイレクト、環境変数の展開 ($VAR) などは利用できません。これらが必要な場合は、処理をスクリプトにまとめて、そのスクリプトを指定してください。

--profile-command でコマンドを指定する

profileCommand の代わりに、--profile-command で認証情報を出力するコマンドを指定することもできます。--profile-command を指定するときは、接続先のカバレッジタイプを --coverage-type で指定してください。

$ soracom sims list --profile-command "/path/to/print-credentials.sh" --coverage-type jp

--profile-command を指定した場合、接続先は以下の順に決まります。

  1. --coverage-type で指定したカバレッジタイプ
  2. --coverage-type を指定しない場合は、プロファイル default のファイルに記載されたカバレッジタイプ
  3. プロファイル default のファイルもない場合は、日本カバレッジ

--profile-command と --profile は組み合わせないでください。認証情報は --profile-command で指定したコマンドの出力から、接続先は --profile で指定したプロファイルから決まるため、意図しない組み合わせになることがあります。

プロファイル default が API Sandbox 用の場合

プロファイル default が SORACOM API Sandbox 用のプロファイルの場合は、--coverage-type を指定しても、API Sandbox にリクエストが送信されます。

AI エージェントに --auth-key-id や --auth-key で認証情報を直接指定させないでください。認証キーシークレットが AI エージェントの会話ログやシェルの履歴に残ります。

リクエストボディをファイルまたは標準入力から渡す

--body に @{ファイルのパス} を指定するとファイルから、- を指定すると標準入力から、リクエストボディを読み込みます。JSON をコマンドラインに直接記述しないため、シェルのクォートやエスケープの誤りを避けられます。Windows でのエスケープについては、SORACOM CLI のヘルプを表示する を参照してください。

ファイルから読み込む例:

$ soracom sims update-speed-class --sim-id 8981100000000000000 --body @request.json

標準入力から読み込む例:

$ echo '{"speedClass":"s1.fast"}' | soracom sims update-speed-class --sim-id 8981100000000000000 --body -

終了コードでコマンドの成否を判定する

新しいバージョンの SORACOM CLI が公開されている場合は、コマンドが成功したときでも、標準エラー出力にその旨のメッセージが出力されます。標準エラー出力に何か出力されたかどうかではなく、終了コードでコマンドの成否を判定してください。

API がエラーを返したときに再試行しない

API がエラーを返した場合、SORACOM CLI はデフォルトで、間隔を空けながら何度か再試行します。--no-retry-on-error を指定すると、再試行せずにすぐにエラーを返します。AI エージェントがコマンドを実行するときにタイムアウトが設定されている場合に便利です。

$ soracom sims list --no-retry-on-error

送受信した HTTP リクエストとレスポンスを確認する

SORACOM_VERBOSE 環境変数に 1 を設定すると、SORACOM CLI が送信した HTTP リクエスト (ヘッダーおよびボディ) と、受信したレスポンスのヘッダーが標準エラー出力に出力されます。コマンドが期待どおりに動作しない場合の調査に利用できます。

set SORACOM_VERBOSE=1

$env:SORACOM_VERBOSE = "1"

SORACOM_VERBOSE=1 soracom sims list

SORACOM_VERBOSE を設定すると、SORACOM CLI が認証のために送信するリクエストも出力されます。このリクエストのボディには、認証キーシークレット (authKey) やパスワードが含まれます。また、値が隠されるヘッダーは X-Soracom-Api-Key と X-Soracom-Token だけで、プロファイルの headers に指定したヘッダーなどはそのまま出力されます。

SORACOM_VERBOSE は調査が必要なときだけ設定し、調査が終わったら設定を解除してください。出力を保存したり共有したりするときは、機密情報が含まれていないことを確認してください。

API キーと API トークンを再利用する

API を呼び出す SORACOM CLI のコマンドは、実行するたびに API キーと API トークンを発行します。AI エージェントがコマンドを何度も実行する場合は、API キーと API トークンを 1 回だけ発行して再利用できます。詳しくは、API キーと API トークンの発行頻度を減らす を参照してください。

© 2015-2026 SORACOM
最終更新日: 2026-10-29
応用的な使いかた : プロキシサーバー経由で使用する
リファレンス : SORACOM CLI のヘルプを表示する
会社概要 プレスルーム お問い合わせ プライバシー 商標 特定商取引法 契約約款
Facebook Twitter Speaker Deck YouTube Blog