> For the complete documentation index, see [llms.txt](https://studio-docs.japan-ai.co.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.japan-ai.co.jp/clirifarensu/cli-members.md).

# CLI Members

`jai-studio members list`は、認証したProjectの有効なメンバーをJSONで一覧取得する読み取り専用コマンドです。宛先候補の確認、担当者の照合、利用者数の把握に使えます。返る表示名、メールアドレス、アバターURLは個人情報になり得るため、取得範囲と出力先を用途に必要な最小限にします。SDKから同じ機能を実装する場合は[SDK Members](/gaidosdk/sdk-members.md)、CLIの導入・プロファイル・共通フラグは[CLIの設定・プロファイル](/clirifarensu/cli-config-and-profiles.md)を参照してください。

## 関連記事

* [SDK Members](/gaidosdk/sdk-members.md)
* [CLIの設定・プロファイル](/clirifarensu/cli-config-and-profiles.md)
* [Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)
* [実行モード・認証・対応範囲](/gaidobito/execution-modes-and-auth.md)

## 始める前に

対象パッケージは`@japan-ai-inc/studio-sdk` **0.11.0**、CLIの実行名は`jai-studio`です。Node.js **22以上**を使い、対象Projectに接続するCLIプロファイル、または安全に設定した接続先とProject APIキーを用意します。接続先とキーの優先順、プロファイルの作成方法、共通フラグは[CLIの設定・プロファイル](/clirifarensu/cli-config-and-profiles.md)を確認してください。

このコマンドは直接開発または明示的に管理された開発自動化で利用します。Project APIキーによる一覧取得には`member:read`スコープが必要です。キーの発行、最小スコープの選択、期限、失効・ローテーションは[Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)に従ってください。

> Project APIキーを`--key`の引数、シェル履歴、CIログ、ソース管理、チャットへ残してはいけません。通常は安全なプロファイルまたは`JAI_STUDIO_API_KEY`を使います。マスクされた`config show`の表示値は認証情報として使えません。

## 利用条件と返る範囲

一覧取得には、認証情報があるだけでなく、次の条件をすべて満たす必要があります。

| 条件         | 確認すること                                                                       |
| ---------- | ---------------------------------------------------------------------------- |
| 組織での提供     | Members APIが組織で利用可能であること。利用できないときは、別の認証情報やAPIで代用せず、組織の管理担当者へ確認します。           |
| APIキーのスコープ | Project APIキーを使う場合、`member:read`が付与されていること。不要な書込み・削除スコープを追加しません。             |
| 呼出し元の権限    | キーまたは呼出し元が、対象Projectのメンバー情報を読むことを許可されていること。                                  |
| Projectの一致 | プロファイルまたは環境変数のキーが、確認したいProjectに対応すること。他のProject・組織のメンバーを指定して取得するコマンドではありません。 |

返るのは有効なProjectメンバーです。各要素の`name`、`email`、`avatarUrl`は`null`の場合があります。画面や後続処理で必須値として扱わないでください。

| 項目              | 内容                        |
| --------------- | ------------------------- |
| `id`            | ProjectメンバーのID            |
| `principalId`   | 利用者を表すID                  |
| `principalType` | 現在は`"user"`               |
| `name`          | 表示名。`null`の場合があります。       |
| `email`         | メールアドレス。`null`の場合があります。   |
| `avatarUrl`     | アバター画像URL。`null`の場合があります。 |
| `createdAt`     | 作成日時を表すISO 8601形式の文字列     |

> 成功時の標準出力にはメンバー情報がそのまま含まれます。メールアドレス、アバターURL、一覧全体を共有ログ、テストfixture、生成例、チケット、クライアント側の永続ストレージへ無条件に保存しないでください。`--pretty`で読みやすくしても、個人情報の取扱いは変わりません。

## 1. メンバーを一覧取得する

```
jai-studio members list [--search <query>] [--cursor <cursor>] [--limit <n>]
```

以下の`<...>`を含む表記は**置換が必要な構文表記**です。角括弧を含めてそのままシェルへ貼り付けず、実際の値に置き換えてください。

位置引数はありません。成功時は`members`、`totalCount`、`nextCursor`を含むJSONを標準出力へ出します。`totalCount`は検索条件に一致するProject全体の件数であり、件数だけが必要な場合に全ページを取得する必要はありません。

| 引数・フラグ              |  必須 | 既定値  | 意味                                            |
| ------------------- | --: | ---- | --------------------------------------------- |
| 位置引数                |   — | —    | ありません。                                        |
| `--search <query>`  | いいえ | 指定なし | 名前またはメールアドレスで絞り込みます。前後の空白は除かれます。              |
| `--cursor <cursor>` | いいえ | 指定なし | 次ページを取得するカーソルです。直前の応答の`nextCursor`をそのまま指定します。 |
| `--limit <n>`       | いいえ | `50` | 1ページの最大件数です。**1〜100**の整数を指定します。               |

まずは検索語を付けず、現在のProjectの最初のページを取得します。

```bash
jai-studio members list --limit 50
```

名前またはメールアドレスで絞り込む例です。

```bash
jai-studio members list --search ada --limit 50
```

`--search`を明示して空文字または空白だけを渡すと、全件取得にはならずエラーになります。全メンバーを対象にする場合は、`--search`自体を省略してください。CLIに`--all`フラグはありません。全ページが必要な場合だけ、次の節のようにカーソルを使います。

## 2. ページングを行う

応答の`nextCursor`が文字列なら、その値を次の同じ検索条件のコマンドへ渡します。`nextCursor`が`null`なら次ページはありません。カーソルは解析、作成、編集せず、そのまま扱ってください。

```
jai-studio members list --search ada --cursor <next-cursor> --limit 50
```

次ページでも`--search`と`--limit`を同じ値に保ちます。検索語、対象Project、または取得処理を変えるときは、以前の`cursor`を再利用しません。取得中にメンバー情報が変わる可能性があるため、複数ページを不変の名簿として保存・利用する処理では、取得時刻と再確認方法を設計してください。

## よくある誤解

### `--search ""`で全件取得できる

できません。明示した空の検索語はCLIでエラーになります。検索せずに一覧を取得する場合は、`--search`を指定しません。

### `--all`で全ページを一度に取得できる

できません。`members list`に`--all`は定義されていません。必要なときだけ、応答の`nextCursor`を使ってページ単位で取得します。

### APIキーを作成できれば一覧を取得できる

できるとは限りません。組織での提供、`member:read`スコープ、呼出し元の権限、対象Projectの一致をすべて確認します。キーのスコープを推測で広げず、[Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)に従い最小スコープのキーを管理してください。

## うまくいかない場合

| 状況                      | 確認・対応                                                                           |
| ----------------------- | ------------------------------------------------------------------------------- |
| `403`でスコープ不足と表示される      | 対象Projectのキーに`member:read`があるか確認します。既存キーの権限を推測で広げず、必要なら最小スコープの新しいキーを発行して切り替えます。 |
| `403`で利用できない、または権限不足になる | 組織で利用可能か、対象Project、呼出し元の権限、実行モードを確認します。組織で提供されない場合があります。                        |
| `400`で取得できない            | `--limit`が1〜100の整数か、検索語が空でないか、カーソルが直前の応答の値かを確認します。                              |
| 認証エラーになる                | キーの失効・削除・有効期限、対象Project、接続先、実値が設定されていることを確認します。マスク表示を使わないでください。                 |
| 出力を共有できない               | 個人情報を含むため、必要な件数や伏せた再現手順だけを共有します。安全な検証環境でも、全件JSONを添付しません。                        |

成功結果は標準出力、エラーは標準エラー出力へJSONで出ます。`--debug`はサーバーの詳細なエラー応答を表示し、機微情報を含む可能性があるため、共有ログでは使いません。問い合わせには対象Project、CLI版、実行モード、操作時刻、検索条件を伏せた再現手順、HTTP状態を記録し、APIキー、認証ヘッダー、メールアドレス、全件出力は含めません。

## チェックリスト

* [ ] Node.js 22以上、CLI版、接続先、対象Projectを確認した
* [ ] 組織で利用可能であり、呼出し元に読み取り権限があることを確認した
* [ ] Project APIキーには必要最小限の`member:read`を付与した
* [ ] APIキーをコマンド引数、履歴、ログ、ソース管理へ残していない
* [ ] `name`、`email`、`avatarUrl`が`null`になり得ることを処理した
* [ ] 次ページでは同じ検索条件と、返却された未変更のカーソルを使う
* [ ] 個人情報をログ、fixture、問い合わせ、共有資料へ残していない

## 次に読む記事

* [SDK Members](/gaidosdk/sdk-members.md)
* [CLIの設定・プロファイル](/clirifarensu/cli-config-and-profiles.md)
* [Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)
* [実行モード・認証・対応範囲](/gaidobito/execution-modes-and-auth.md)
