gws-cli

gws-cli

手書きの HTTP リクエストや場当たり的な API ラッパーではなく、Google Workspace CLI を使ってタスクを実行する場合に、このスキルを使用します。

このスキルを使用する場面

• Google Drive、Gmail、Sheets、Docs、Slides、Calendar、Chat、Tasks、People、Meet、または Workspace Admin API との連携をユーザーから依頼された場合。
• エージェントが調べやすい、構造化された JSON 出力をユーザーが求めている場合。
• リクエストを作成する前に、Google API のスキーマを調べる必要がある場合。
• ローカル、CI、またはヘッドレス環境で実行できる、再現可能な CLI ワークフローをユーザーが求めている場合。

必須の運用モデル

1. gws がインストールされ、PATH から利用できることを確認します。
2. API を呼び出す前に、認証状態を確認します。
3. フラグを組み立てる前に、gws schema または gws <service> --help で対象のメソッドを調べます。
4. まず読み取り専用のコマンドを優先します。
5. 書き込み、更新、削除の操作を実行する前に、ユーザーに意図を確認します。
6. コマンドがローカルでの検証に対応しており、操作にリスクがある場合は、--dry-run を優先します。

クイックスタート

# Install the CLI
npm install -g @googleworkspace/cli

# Check the binary and auth status
bash scripts/check-prereqs.sh

# Inspect command space
gws drive --help
gws schema drive.files.list

# Run a read-only command
gws drive files list --params '{"pageSize": 10}' --format json

認証ワークフロー

タスクを満たす中で最も簡易な認証フローを選択します。

ローカルでの対話型認証

gws auth setup
gws auth login

サービスアカウント

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
gws auth status

CI またはヘッドレス環境でのフロー

• エクスポートした認証情報、またはサービスアカウントに基づく実行を優先します。
• シークレットをユーザーにそのまま表示しないでください。
• 認証情報が不足している場合は、推測せずに停止し、適切な認証設定を依頼してください。

詳細は references/REFERENCE.md を参照してください。

コマンドの確認ワークフロー

実行前に必ず調べてください。

# Browse resources and helper commands for a service
gws sheets --help

# Inspect a specific method schema
gws schema sheets.spreadsheets.values.get

スキーマの出力を使って、次の項目を確認します。

• 必須の --params 値
• --json を使ったリクエスト本文が必要かどうか
• ページネーションまたはファイルアップロードのフラグが適用されるかどうか
• API が想定するフィールド名と型

コマンドのパターン

読み取り専用の一覧取得または取得

gws drive files list --params '{"pageSize": 10}' --format json
gws gmail users messages get --params '{"userId": "me", "id": "MESSAGE_ID"}' --format json

明示的な確認を伴う作成または更新

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}' --format json
gws docs documents batchUpdate --params '{"documentId": "DOC_ID"}' --json '{"requests": [...]}' --format json

スキーマに基づくリクエストの作成

gws schema calendar.events.insert
gws calendar events insert --params '{"calendarId": "primary"}' --json '{"summary": "Standup", "start": {"dateTime": "2026-03-07T09:00:00Z"}, "end": {"dateTime": "2026-03-07T09:15:00Z"}}'

ページネーション

gws drive files list --params '{"pageSize": 100}' --page-all

ファイルのアップロードまたはダウンロード

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf
gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' --output ./download.bin

安全に関するルール

• create、insert、update、patch、delete と、状態を変更するヘルパーコマンドは、書き込み操作として扱います。
• 書き込み操作を実行する前に、対象のリソース、ID、スコープを確認します。
• トークン、OAuth クライアントシークレット、またはサービスアカウント JSON の内容を決して表示しないでください。
• ユーザーが人向けの表を明示的に希望している場合を除き、--format json を優先します。
• 出力形式が NDJSON に変わるため、--page-all は意図的に使用します。
• 上流 API または CLI のヘルプが曖昧な場合は、フラグ名を推測せず、スキーマを再度調べます。

利用可能なサポートファイル

• インストール、認証、一般的なコマンドのテンプレートについては references/REFERENCE.md を参照してください。
• ローカル環境の確認には scripts/check-prereqs.sh を使用します。

トラブルシューティング

• gws が見つからない場合は、npm または GitHub リリースからインストールし、PATH に含まれていることを確認してから、bash scripts/check-prereqs.sh を再実行してください。
• gws auth status で認証情報がないと表示された場合は、gws auth setup と gws auth login を実行するか、サービスアカウントを使うフローでは GOOGLE_APPLICATION_CREDENTIALS をエクスポートしてください。
• OAuth クライアントの制限により gws auth login が失敗する場合は、適切であれば上流の手動 OAuth フロー、またはサービスアカウントを優先してください。
• リクエストが 403 Forbidden または権限不足を返した場合は、再試行する前に、現在の ID、API の有効化状態、スコープ、リソースの共有設定を確認してください。
• メソッドが不明な場合は、REST メソッド名にそのまま対応すると推測せず、gws <service> --help でサービスのエイリアスを確認してください。
• リクエストがスキーマ検証に失敗した場合は、gws schema <service.resource.method> を再実行し、必須フィールド名を、作成したコマンドと一つずつ照合してください。
• --page-all によって予期せず出力形式が変わった場合は、ページネーション時の出力が NDJSON になることを思い出し、1 行ずつ解析してください。