Google Workspace CLI — クイックインストール

前回のセットアップから OAuth 認証情報を使用して、別のマシンに gws をインストールします。認証済みの CLI を作成し、すべてのエージェント スキルを使用できます。

前提条件: ユーザーは前回の gws-setup (または Google Cloud Console) から client_secret.json を持っている必要があります。持っていない場合は、代わりに gws-setup スキルを使用してください。

ワークフロー

ステップ 1: 事前チェック

which gws && gws --version
ls ~/.config/gws/client_secret.json
gws auth status

既に正しいスコープで認証済みの場合は、ステップ 4 にスキップしてください。

ステップ 2: CLI をインストール

npm install -g @googleworkspace/cli
gws --version

ステップ 3: 認証情報をセットアップ

ユーザーに client_secret.json を提供するよう求めます。3 つのオプションがあります:

オプション A — JSON コンテンツを貼り付け:

ユーザーに JSON を貼り付けるよう求めます。~/.config/gws/client_secret.json に書き込みます:

mkdir -p ~/.config/gws

期待される形式:

{
  "installed": {
    "client_id": "...",
    "project_id": "...",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_secret": "...",
    "redirect_uris": ["http://localhost"]
  }
}

オプション B — ファイル パス:

ユーザーがローカルでファイルを持っている場合 (例: Downloads):

mkdir -p ~/.config/gws
cp /path/to/client_secret.json ~/.config/gws/client_secret.json

オプション C — 環境変数:

export GOOGLE_WORKSPACE_CLI_CLIENT_ID="your-client-id"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="your-client-secret"

ステップ 4: 認証

重要: このステップでは、ユーザーがブラウザで開く必要がある非常に長い OAuth URL (30 以上のスコープ) が出力されます。URL は非常に長いため、ターミナル出力からコピーできません。複数行に折り返され、破損します。常にファイルに抽出し、プログラムで開いてください。

どの Google アカウントを使用するかを尋ねてから:

1. バックグラウンドで認証を実行して出力をキャプチャ:

gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks 2>&1 | tee /tmp/gws-auth-output.txt

バックグラウンド タスクとして実行しても問題ありません。ユーザーがブラウザで承認すると完了します。

2. URL を抽出して開く (出力が表示された後に別途実行):

grep -o 'https://accounts.google.com[^ ]*' /tmp/gws-auth-output.txt > /tmp/gws-auth-url.txt
cat /tmp/gws-auth-url.txt | xargs open

open が機能しない場合、ユーザーに伝えます: 「認証 URL は /tmp/gws-auth-url.txt に保存されています。そのファイルを開き、そこから URL をコピーしてください。」

3. ユーザーがブラウザで承認するまで待機してから検証:

gws auth status

別案 — すべてのスコープの --full:

gws auth login --full

ユーザーは元のマシンで gws auth status を実行して、付与されたスコープを確認できます。

ステップ 5: エージェント スキルをインストール

npx skills add googleworkspace/cli -g --agent claude-code --all

これにより 90 以上のスキルが ~/.claude/skills/ にインストールされます。スキルが既にインストールされている場合は、再実行しても安全です。

ステップ 6: 検証

gws auth status
gws calendar +agenda --today
gws gmail +triage

---

トラブルシューティング

「Auth error — credentials missing or invalid」(終了コード 2)

• ~/.config/gws/client_secret.json が存在し、有効な JSON が含まれていることを確認
• gws auth login を再実行

トークンの有効期限切れ

• GCP アプリが「Testing」ステータスの場合、トークンは 7 日後に期限切れになります
• gws auth login を再実行してリフレッシュ
• 永続トークンの場合は、GCP Console OAuth 同意画面でアプリを Production にプッシュ

Claude Code にスキルが表示されない

• スキルはセッション開始時にロードされます。インストール後に Claude Code を再起動してください
• 検証: ls ~/.claude/skills/gws-* | wc -l は 30 以上のディレクトリを表示するはずです

関連項目

• gws-setup — GCP プロジェクト作成を含む初回セットアップ
• gws-shared — 認証パターンとグローバル フラグ