gwsとGemini CLIが示すAIのための
CLI設計
（JSON出力）

by
  • CLIツールの設計は、使い手が人間かAIエージェントかによって求める仕様が異なります。
  • Google WorkspaceのCLIツール「gws」は、全レスポンスを構造化JSONで返し、コマンド体系をAPIから動的に生成するなど、AIが扱いやすい設計を出発点としています。
  • 一方Gemini CLIは人間向けのインタラクティブな使い方を主軸に置き、JSON出力はフラグで切り替える方式を採っています。
  • 二つのツールは「誰をデフォルトの使い手とするか」という設計の前提が異なり、その違いがコマンド体系や出力形式の随所に現れています。

関連記事

1. AIが使うコマンドラインツール

コマンドラインツールの設計が、静かに変わりつつあります。変化の背景にあるのは、CLIを使う「誰か」が、人間だけではなくなってきたという事実です。

AIが使うとき何が変わるか 人間 AI エージェント インタラクティブ入力 問い返し → ユーザーが答える 動作停止 待機 → タイムアウト 色付き整形出力 ANSIエスケープで装飾 パース障害 余分な文字列が混入 説明文エラー “Something went wrong” 判断不能 構造化エラーが必要 AIには：全引数を最初から渡せる設計 ＋ JSON出力 ＋ 構造化エラー

GoogleのWorkspace向けCLI「gws」は、そのREADMEの冒頭でこう説明されています。”One CLI for all of Google Workspace — built for humans and AI agents.” 人間のためでもあり、AIエージェントのためでもある、と最初から宣言している点が特徴的です1。

1.1. 従来のCLIが積み上げてきた作法

人間がコマンドラインを使うとき、ツールには「使い方を教えながら動かせること」が求められてきました。--help を打てばオプション一覧が表示され、タブ補完で候補が出る。必須引数が足りなければインタラクティブに問い返し、デフォルト値で補完する。出力は目で見て状況をすぐ把握できるよう、色付きのログや整形された表として返ってきます。

こうした設計思想は、エラーが起きたときにも現れます。”Something went wrong. Please try again.” という一文は、人間が読んで状況を判断するには十分かもしれません。けれどAIエージェントが使い手になると、これらの設計がそのまま機能しなくなります。

1.2. AIが使うとき何が変わるか

AIエージェントはCLIを「読んで理解する」のではなく、「呼び出して出力をパースする」形で使います。この違いは、設計上の影響が大きいです。

インタラクティブなプロンプトは、AIにとって動作を止める壁になります。コミットメッセージの入力を求めてターミナルが待機状態になっても、AIは入力できません。エラーで止まるかタイムアウトするかのどちらかです。すべての必要情報を最初のコマンド引数として渡せることが、AIが使えるCLIの前提条件になります。

出力の整形も逆効果になります。ANSIエスケープシーケンスで色づけされた表は、AIがパターンマッチで解析しようとすると邪魔な文字列になります2。AIが扱いやすい出力はJSON、あるいは余分な装飾を持たない構造化テキストです。エラーメッセージについても、人間向けの説明文よりエラーコードと失敗理由が構造化されている方が、AIは次の行動を判断できます。

2. gwsが選んだ設計

gwsは、こうしたAI側の要件を出発点として設計されています。

gwsが選んだ設計 gws JSON出力 デフォルトで構造化 動的コマンド生成 Discovery Service連携 インラインJSON引数 –params / –json MCPサーバー Claude / Gemini CLI連携 Model Armor連携 –sanitize フラグ

全レスポンスが構造化JSONで返り、エラー出力にも機械が読めるフィールドが含まれます。エラーが出たとき、gwsはJSON本体と同時にstderrへアクション可能なヒントを出力します。APIが無効になっているなら、有効化するためのURLをエラーオブジェクト内の enable_url フィールドに含めて返す。人間が読んでも分かりますし、AIがパースしても使えます。

コマンド体系の作り方も特徴的です。gwsはコマンド一覧を静的に持たず、GoogleのDiscovery Serviceをランタイムで読み込んで動的にコマンドツリーを構築します3。APIが増えれば自動でコマンドが増え、仕様の更新に合わせてCLIの定義を手で書き直す必要がありません。

引数の渡し方も、AIが操作しやすい形を意識しています。

gws drive files list --params '{"pageSize": 10}'
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
Code language: PHP (php)

オブジェクト構造をインラインJSONとしてそのまま渡せます。ファイルに書き出してパスを渡すという間接的な手順が不要で、AIがパラメータを生成してそのまま引数に埋め込めます。

--dry-run フラグで実際のAPI呼び出しを行わずリクエスト内容を確認でき、--page-all で自動ページネーションも使えます。MCPサーバーモードではWorkspace APIをMCP対応クライアントから直接呼び出せます。またAIエージェントがAPIレスポンスを受け取る前にその内容をスキャンする --sanitize フラグも備えており、Google CloudのModel Armorと連携してプロンプトインジェクション攻撃を検出・ブロックできます4。

gws mcp -s drive,gmail,calendar

このコマンドでMCPサーバーを起動すると、Claude DesktopやGemini CLIといったMCP対応クライアントが、gwsを介してWorkspaceを操作できるようになります5。

2.1. Gemini CLIの別のアプローチ

Googleが公開しているもう一つのCLIツール、Gemini CLIは別の方向性を見せています6。

Gemini CLIが取った別のアプローチ 人間向け（デフォルト） $ gemini -p “…” 読みやすい テキスト出力 ▊ インタラクティブ操作 カラー表示・対話型 ← デフォルト フラグで切替 AI向け（オプトイン） –output-format json {“result”: “…”, “status”: “ok”} stream-json も可 構造化JSON出力 改行区切りストリーム ← フラグ指定で有効

こちらは「AIをターミナルに持ち込む」ためのツールで、開発者がGeminiと対話しながら作業するインタラクティブな使い方を主軸に置いています。

AI向けの出力については、明示的なフラグで切り替える設計です。

gemini -p "Explain the architecture of this codebase" --output-format json
gemini -p "Run tests and deploy" --output-format stream-json
Code language: JavaScript (javascript)

通常時は人間が読みやすい出力を返し、--output-format json を渡したときだけ構造化JSONになります。ストリーミングが必要なら stream-json を指定すると、改行区切りのJSONイベントが流れてきます。人間向けの快適さをデフォルトに保ちつつ、機械が扱いやすい経路をフラグで明示するという構造です。

3. 二つの設計が示す分岐点

gwsとGemini CLIは、同じ課題への異なる答えを示しています。

二つの設計が示す分岐点 誰がデフォルトの使い手か？ gws AI が主な使い手 JSON出力がデフォルト 構造化エラー 動的コマンド生成 人間向けはオプション Gemini CLI 人間が主な使い手 対話型がデフォルト カラー・整形出力 AIターミナルに統合 AI向けはフラグで切替 前提の置き方が違うだけで、設計の重心がすべて変わる

gwsは「AIが主要な使い手になる」という前提からツールを組み立て、人間向けの使いやすさをそこに重ねています7。出力はデフォルトでJSONであり、エラーは構造化されており、コマンド体系はAPIの仕様から自動生成されます。人間には --help と --dry-run が用意されています。

Gemini CLIは人間が使うことを主軸に設計されていて、AIが使う場面はフラグで切り替えます。人間にとっての快適さがデフォルトで、機械向けの出力はオプトインです。

どちらが正しいかという問いよりも、「誰が主な使い手か」という前提をどこに置くかで、設計の重心が変わります。

3.1. 仕様が露出されることの意味

gwsのもう一つの特徴として見落とせないのが、スキーマを直接確認できるコマンドの存在です。

仕様の露出とCLIの問い 仕様を露出する $ gws schema drive.files.list → リクエスト/レスポンス定義 人 ドキュメント代わりに その場で確認 AI 動的にスキーマを読み 引数を自動生成 CLIが問い直すもの 「使いやすくするか」 ← 従来の問い ↓ 「誰にとって使いやすいか」 ← AI時代の問い gwsは両方の答えを 同じ設計に収める For humans ＋ For AI agents — 一つのCLIで両立する 
gws schema drive.files.list
Code language: CSS (css)

任意のAPIメソッドのリクエスト・レスポンス定義をその場で確認できます。人間がドキュメントを参照する代わりに使えますし、AIが動的にスキーマを読んで引数を組み立てることもできます。ドキュメントと定義が同じツールの中に同居している状態です。

CLIが「仕様を露出するインターフェース」として機能するという考え方です。人間向けの説明と機械が参照できる定義を分離せずに一つのツールで扱うことで、運用現場で解釈がずれるリスクを設計の段階で小さくできます。

3.2. CLIが誰に向けて作られるかという問い

gwsのREADMEには “For humans” と “For AI agents” が並んで書かれています。どちらかではなく両方を同じツールで扱おうとする意図が、設計のあちこちに現れています。

Gemini CLIはその逆で、人間のための道具としてターミナルにAIを持ち込み、スクリプトやパイプラインで使う場合には出力形式を明示的に指定させます。

AIがCLIを日常的に呼び出す現在、設計の問いは「使いやすくするか」から「誰にとって使いやすいか」へ移っています。gwsはその問いに、二つの答えを同じ設計に収めようとすることで応えています8。

  1. gwsはGoogleが公式にサポートするプロダクトではなく、READMEにも “This is not an officially supported Google product.” と明記されている。オープンソースプロジェクトとして開発が続けられており、2025年3月時点でv0.3.5がリリースされている。 – googleworkspace/cli – GitHub
  2. ANSIエスケープシーケンスとは、ターミナル上でテキストの色や書式を制御するための特殊な文字列で、\e[31m（赤色）や\e[0m（リセット）のような形をとる。人間の目には色として見えるが、テキストとして受け取るプログラムには余分なバイト列として混入する。 – ANSI escape code – Wikipedia
  3. Google Discovery Serviceは、Google APIのメソッド・パラメータ・レスポンス形式を機械可読なJSONドキュメントとして公開するサービス。APIごとにエンドポイント情報やスキーマが含まれており、ツールやSDKが動的にAPI仕様を取得するために使われる。 – Google API Discovery Service – Google Developers
  4. Model ArmorはGoogle CloudのAIセキュリティサービスで、LLMへのプロンプト入力とレスポンス出力の両方をリアルタイムでスキャンする。プロンプトインジェクション・ジェイルブレイク検出、機密データ保護、有害コンテンツフィルタリングなどの機能を持つ。 – Model Armor overview – Google Cloud Documentation
  5. MCP（Model Context Protocol）は、AIエージェントと外部ツール・データソースを繋ぐためのオープン標準プロトコル。Anthropicが2024年に提唱し、その後広く採用が進んだ。MCPサーバーとしてサービスを公開すると、Claude、Gemini CLIなどMCP対応クライアントから統一的なインターフェースで呼び出せるようになる。 – Model Context Protocol – modelcontextprotocol.io
  6. Gemini CLIは2025年6月25日にオープンソース（Apache 2.0）で公開された。Claude CodeやOpenAI Codex CLIと競合するAIコーディングツールとして位置づけられており、個人アカウントで1分60リクエスト・1日1000リクエストまで無料で利用できる。 – Google unveils Gemini CLI, an open source AI tool for terminals – TechCrunch
  7. gwsはRustで実装されており、リポジトリのコードの99.3%がRustで書かれている。Rustを選んだことで、バイナリサイズの小ささとメモリ安全性を両立しつつ、npm経由でネイティブバイナリを配布できる構造になっている。 – googleworkspace/cli – GitHub
  8. gwsのGitHubリポジトリは2025年3月時点でスター数5,100超、フォーク数138。2026年3月5日にv0.3.5がリリースされており、現在も活発に開発が続いている。 – googleworkspace/cli – GitHub