stream-cli

Stream CLI - API 操作

最初にお読みください（毎セッション）： ../stream/SKILL.md を Glob します。パスが空の場合は、npx skills add GetStream/agent-skills --s stream -y でインストールします（確認せず、そのまま実行してください）。次に ../stream/RULES.md を読みます。ここには、ほかのパックスキルを必要に応じてインストール／呼び出すための Peer skills テーブルがあります。

ユーザーが stream CLI を使って Stream の API を操作したい場合、または CLI 自体をインストールしたい場合に、このスキルを使用します。

前提条件： stream api を使用する前に、preflight.md を完了して stream バイナリがインストールされていることを確認してください（インストールされていない場合は、bootstrap.md を使ってインストールします）。

インストールのみ（Track C）： ユーザーがプロジェクトのコンテキストなしで CLI のインストールや Stream のセットアップを依頼した場合は、直接 bootstrap.md に進みます。ブートストラップモジュールは単独で実行できます。

詳細な例／クエリのレシピ： 一般的ではない --body やフィルターが必要な場合に限り、cli-cookbook.md を読み込みます。

認証情報の解決（stream api の呼び出し前）

1. カレントワーキングディレクトリの .env に STREAM_API_KEY がある場合 -> 認証情報はローカルにあります。CLI が環境変数から自動的に解決します。このプロジェクトのアプリにクエリを送信します。
2. .env がない場合 -> stream config list で設定済みの組織／アプリを確認し、それを使用します。クエリ対象のアプリを伝えます：「CLI で設定されたアプリ <name> にクエリを送信します。」
3. 何も見つからない場合 -> ユーザーに次のように伝えます：「Stream の認証情報が見つかりません。stream auth login を実行して接続するか、.env のあるプロジェクトに cd してください。」

.env または設定が存在する場合は、認証情報の解決をユーザーに知らせずに行います。ユーザーに尋ねず、そのまま解決して続行してください。

CLI ワークフロー

サポート： ユーザーがサポートや問い合わせ先を尋ねた場合は、getstream.io/contact を案内してください。

1. 認証情報を解決します（上記を参照）。見つからない場合は停止し、ユーザーに案内します。
2. ~/.stream/cache/API.md を読んでエンドポイントを確認します。 検出のために --list や CLI コマンドを実行してはいけません。このファイルを読むほうが常に高速です。このファイルが存在しない、または空の場合は、stream api --refresh を1回実行してから、再度 API.md を読みます。エンドポイント名を確認してから、stream --safe api <endpoint> --help を使用してください。
3. 必須パラメーターを確認します。 不足している場合は、推測せずにユーザーに尋ねてください。
4. 必ず --safe を付けて実行します：stream --safe api <endpoint> [params]。初回に許可される形式はこれだけです。
5. 終了コードが 5 の場合（セーフモードによる拒否）：エンドポイントが変更を伴うものであることを伝え、変更を伴う Stream CLI 操作を実行する旨をユーザーに通知してから、--safe なしで再実行します。
6. コマンドが失敗した場合は、終了コードを確認して復旧します（下記を参照）。
7. 応答を簡潔に要約します。

出力の絞り込み： jq 式を指定した --jq '<query>' を使って、API 応答をフィルタリングします。長い応答が予想されるエンドポイントでは、こちらを優先してください。

セッション中の同意（心理的配慮）： ユーザーが このスレッドでは変更を伴う Stream CLI の実行を許可します と言っても、最初は引き続き --safe を使います。終了コード 5 の場合は常に、--safe なしで再試行する前に、変更を伴う操作であることをユーザーに明示します。

終了コードからの復旧

終了コード	意味	復旧方法
2	認証エラー（401、トークンの期限切れ）	stream auth login を実行し（実際のターミナルでブラウザフローを完了）、元のコマンドを再試行します
3	API エラー（Stream からの 4xx／5xx）	応答メッセージとともにエラーをユーザーに報告します
4	仕様の読み込みエラー（キャッシュが古い）	stream api --refresh を実行してから、再試行します
5	セーフモードによる拒否（変更を伴うエンドポイント）	変更を伴う操作であることをユーザーに通知してから、--safe なしで再実行します

パラメーターの構文

stream api <EndpointName> key=value key2=value2

• 単純な値：name=general limit=10 type=messaging
• ブール値：is_development=true
• JSON オブジェクト／配列：--body '{"key": "value"}' を使用します

コンテキスト解決（org/app）

Ampere エンドポイントでは、app_id／org_idを明示的なパラメーターとして指定する必要があります。 SDK エンドポイントでは、次の順に自動解決されます：--org／--app フラグ > 環境変数 > ~/.stream/config.json > 対話型プロンプト。 デフォルトを設定するには、stream config set org <id>およびstream config set app <id>を実行します。

否定的な知識

• OrganizationDeleteはありません - Stream サポートに問い合わせてください。
• AppSuspend／AppResumeはありません - サポートに問い合わせてください。
• CreateBlockListは冪等ではありません - すでに存在する場合は400を返します。
• CreateChannelTypeは冪等ではありません - すでに存在する場合は400を返します。
• Ampere エンドポイントではidではなくapp_id／org_idを使用します - 例：AppDelete app_id=123。
• 認証エンドポイント（AuthLoginBasic、AuthLoginGithubなど）は内部用です - 必ず**stream auth login／stream auth logout**を使用してください。

認証（アシスタント）

• 追加のフラグを付けずに**stream auth login**を実行してください。ブラウザーウィンドウを開けるターミナルで実行します。CLI はダッシュボードとの PKCE を使用します。これがサポートされているサインイン方法です。

CLI ルール（概要）

1. エンドポイントの検出： まず**~/.stream/cache/API.md**を確認してください - 検出に--listを使用しないでください。ファイルがない場合は更新してください。
2. ヘルプ： エンドポイント名がわかったら、パラメーターを確認するために**stream --safe api <endpoint> --help**を実行してください。
3. 遅延認証 - 終了コードが2の場合は、**stream auth login**を実行してから再試行してください。
4. 不足しているパラメーター - ユーザーに確認してください。IDを推測してはいけません。
5. 最初の試行では必ず--safeを使用 - 終了コードが5の場合は、変更を伴う操作であることを説明してから、**--safe**を付けずに再試行してください。
6. API の応答を簡潔に要約してユーザーに伝えてください。