"The command line is the most efficient interface ever invented — if you know what you're doing." — Rob Pike
「命令列是人類發明過最高效的介面——前提是你知道自己在做什麼。」—— Rob Pike
What Is Google Workspace CLI?
gws is an open-source command-line tool for interacting with Google Workspace APIs — Gmail, Calendar, Drive, Sheets, and more. Built in Rust, it dynamically constructs its command surface from Google's Discovery Service, meaning new API endpoints become available automatically without a software update.
Key facts:
- Repo: googleworkspace/cli
- Language: Rust
- License: Apache 2.0
- Status: Pre-v1.0, actively developed, breaking changes expected
- Not an officially supported Google product — this is important to understand before relying on it in production
This guide focuses exclusively on Gmail and Google Calendar — the two services most useful for personal productivity from the terminal.
什麼是 Google Workspace CLI？
gws 是一個開源命令列工具，用於操作 Google Workspace API——包括 Gmail、Calendar、Drive、Sheets 等。它以 Rust 編寫，在執行時從 Google Discovery Service 動態建構指令介面，這意味著 Google 新增 API 端點時，不需要更新軟體就能使用。
重點資訊：
- 儲存庫： googleworkspace/cli
- 語言： Rust
- 授權： Apache 2.0
- 狀態： 尚未到 v1.0，積極開發中，可能有破壞性變更
- 這不是 Google 官方支援的產品——在依賴它之前，請務必理解這一點
本文僅聚焦於 Gmail 和 Google Calendar 這兩個對個人生產力最有幫助的服務。
Step 1: Installation
Three installation methods, pick whichever suits your environment:
Option A: npm (Recommended)
Requires Node.js 18+. This bundles pre-built native binaries — no Rust toolchain needed.
npm install -g @googleworkspace/cliOption B: Cargo (Build from Source)
Requires the Rust toolchain installed via rustup.
cargo install --git https://github.com/googleworkspace/cli --lockedOption C: Nix
nix run github:googleworkspace/cliVerify installation:
gws --versionSecurity note: Always install from the official repo or npm registry. Do not use third-party forks or unofficial binaries.
第一步：安裝
三種安裝方式，依你的環境選擇：
方案 A：npm（推薦）
需要 Node.js 18+。這會包含預編譯的原生二進位檔案，不需要 Rust 工具鏈。
npm install -g @googleworkspace/cli方案 B：Cargo（從原始碼編譯）
需要透過 rustup 安裝 Rust 工具鏈。
cargo install --git https://github.com/googleworkspace/cli --locked方案 C：Nix
nix run github:googleworkspace/cli驗證安裝：
gws --version安全提醒： 務必從官方儲存庫或 npm registry 安裝。不要使用第三方 fork 或非官方的二進位檔案。
Step 2: Create a Google Cloud Project (Manual Setup)
The gws auth setup command can automate this, but requires the gcloud CLI. For full control and understanding, here's the manual approach:
- Go to Google Cloud Console
- Create a new project — name it something like
gws-personal-cli - Enable APIs:
- Navigate to "APIs & Services" → "Library"
- Search and enable Gmail API
- Search and enable Google Calendar API
- Do not enable APIs you don't need — every enabled API is a potential attack surface
- Configure OAuth Consent Screen:
- Choose "External" as user type
- Fill in app name (e.g.,
My GWS CLI) - Add your email as a test user under "Test users"
- Leave the app in Testing mode — do not publish it
- Create OAuth Credentials:
- Go to "Credentials" → "Create Credentials" → "OAuth client ID"
- Application type: Desktop app
- Download the JSON file
- Place the credentials file:
mkdir -p ~/.config/gws
mv ~/Downloads/client_secret_*.json ~/.config/gws/client_secret.json
chmod 600 ~/.config/gws/client_secret.jsonThe chmod 600 ensures only your user account can read the file.
第二步：建立 Google Cloud 專案（手動設定）
gws auth setup 指令可以自動完成這些步驟，但需要安裝 gcloud CLI。為了完全掌控和理解每一步，以下是手動方式：
- 前往 Google Cloud Console
- 建立新專案——命名為例如
gws-personal-cli - 啟用 API：
- 導航到「APIs & Services」→「Library」
- 搜尋並啟用 Gmail API
- 搜尋並啟用 Google Calendar API
- 不要啟用你不需要的 API——每個啟用的 API 都是潛在的攻擊面
- 設定 OAuth 同意畫面：
- 使用者類型選擇「External」
- 填入應用程式名稱（例如
My GWS CLI） - 在「Test users」底下加入你自己的 email
- 將應用程式維持在 Testing 模式——不要發布
- 建立 OAuth 憑證：
- 前往「Credentials」→「Create Credentials」→「OAuth client ID」
- 應用程式類型選擇 Desktop app
- 下載 JSON 檔案
- 放置憑證檔案：
mkdir -p ~/.config/gws
mv ~/Downloads/client_secret_*.json ~/.config/gws/client_secret.json
chmod 600 ~/.config/gws/client_secret.jsonchmod 600 確保只有你的使用者帳號能讀取這個檔案。
Step 3: Login With Minimal Scopes
This is the most critical security step. The default recommended scope preset requests 85+ permissions — far more than you need for Gmail and Calendar.
Login with only Gmail and Calendar scopes:
gws auth login -s gmail,calendarThis requests only the scopes necessary for Gmail and Calendar operations. When the browser opens, review the permissions carefully before granting access.
What this grants:
| Scope | What It Allows |
|---|---|
gmail | Read, send, delete, and manage your email and settings |
calendar | Read, edit, share, and delete your calendars and events |
What you should NOT do:
- Do not use
gws auth loginwithout-s— it defaults torecommendedwhich requests 85+ scopes - Do not use
-s recommendedunless you actually need access to Drive, Sheets, Docs, and many other services - Do not grant permissions to scopes you don't understand
Verify your login:
gws auth statusCredential storage: Credentials from gws auth login are encrypted at rest with AES-256-GCM, with the encryption key stored in your OS keyring (macOS Keychain / Linux secret-service / Windows Credential Manager). This is significantly more secure than a plaintext JSON file.
第三步：以最小權限登入
這是最關鍵的安全步驟。預設的 recommended 範圍預設會請求超過 85 個權限——遠超你操作 Gmail 和 Calendar 所需。
只使用 Gmail 和 Calendar 範圍登入：
gws auth login -s gmail,calendar這只會請求 Gmail 和 Calendar 操作所需的範圍。當瀏覽器開啟時，請仔細檢視權限再授予存取。
這會授予什麼：
| 範圍 | 允許的操作 |
|---|---|
gmail | 讀取、傳送、刪除、管理你的電子郵件和設定 |
calendar | 讀取、編輯、分享、刪除你的日曆和活動 |
你不應該做的事：
- 不要在沒有
-s的情況下執行gws auth login——預設是recommended，會請求超過 85 個範圍 - 不要使用
-s recommended，除非你真的需要存取 Drive、Sheets、Docs 和許多其他服務 - 不要對你不理解的範圍授予權限
驗證登入狀態：
gws auth status憑證儲存： 透過 gws auth login 取得的憑證會以 AES-256-GCM 加密儲存，加密金鑰保存在你的作業系統金鑰鏈中（macOS Keychain / Linux secret-service / Windows Credential Manager）。這比明文 JSON 檔案安全得多。
Gmail: Essential Commands
Send an Email
gws gmail +send \
--to recipient@example.com \
--subject "Meeting follow-up" \
--body "Thanks for the meeting today. Here are the action items..."The +send helper automatically handles RFC 2822 formatting and base64 encoding. You'll be prompted for confirmation before the email is actually sent.
Triage Your Inbox
# Show top 20 unread messages (default)
gws gmail +triage
# Show top 10 unread messages
gws gmail +triage --max 10
# Filter with Gmail search syntax
gws gmail +triage --query "from:boss@company.com is:unread"
# Include label information
gws gmail +triage --labelsWatch for New Emails (Streaming)
gws gmail +watchThis outputs incoming emails as an NDJSON stream — useful for piping into other tools or for real-time monitoring.
Raw API Operations
For more advanced operations, use the raw API commands:
# List messages matching a query
gws gmail users messages list --user-id me --q "subject:invoice after:2026/01/01"
# Get a specific message
gws gmail users messages get --user-id me --id MESSAGE_ID
# List all labels
gws gmail users labels list --user-id me
# Trash a message
gws gmail users messages trash --user-id me --id MESSAGE_ID
# Create a new label
gws gmail users labels create --user-id me --json '{"name": "Receipts", "labelListVisibility": "labelShow"}'
# Get vacation settings
gws gmail users settings getVacation --user-id meGmail：常用指令
寄送郵件
gws gmail +send \
--to recipient@example.com \
--subject "Meeting follow-up" \
--body "Thanks for the meeting today. Here are the action items..."+send 輔助指令會自動處理 RFC 2822 格式化和 base64 編碼。在郵件實際寄出前，會提示你確認。
整理收件匣
# 顯示前 20 封未讀訊息（預設）
gws gmail +triage
# 顯示前 10 封未讀訊息
gws gmail +triage --max 10
# 使用 Gmail 搜尋語法過濾
gws gmail +triage --query "from:boss@company.com is:unread"
# 包含標籤資訊
gws gmail +triage --labels即時監聽新郵件（串流）
gws gmail +watch這會將收到的郵件以 NDJSON 串流輸出——適合串接到其他工具或做即時監控。
原始 API 操作
更進階的操作可以使用原始 API 指令：
# 列出符合查詢條件的訊息
gws gmail users messages list --user-id me --q "subject:invoice after:2026/01/01"
# 取得特定訊息
gws gmail users messages get --user-id me --id MESSAGE_ID
# 列出所有標籤
gws gmail users labels list --user-id me
# 將訊息移至垃圾桶
gws gmail users messages trash --user-id me --id MESSAGE_ID
# 建立新標籤
gws gmail users labels create --user-id me --json '{"name": "Receipts", "labelListVisibility": "labelShow"}'
# 取得休假設定
gws gmail users settings getVacation --user-id meGoogle Calendar: Essential Commands
View Your Agenda
# Today's events
gws calendar +agenda --today
# Tomorrow's events
gws calendar +agenda --tomorrow
# This week
gws calendar +agenda --week
# Next 3 days
gws calendar +agenda --days 3
# Specific calendar
gws calendar +agenda --today --calendar "Work"
# Table format for better readability
gws calendar +agenda --week --format tableCreate an Event
gws calendar +insert \
--summary "Team standup" \
--start "2026-03-10T09:00:00+08:00" \
--end "2026-03-10T09:30:00+08:00" \
--location "Conference Room A" \
--description "Daily sync meeting" \
--attendee alice@example.com \
--attendee bob@example.comTime values must be in RFC 3339 format. Include timezone offset (e.g., +08:00 for Taipei) to avoid ambiguity. The --attendee flag is repeatable for multiple invitees.
Raw API Operations
# List upcoming events
gws calendar events list --calendar-id primary --time-min "2026-03-09T00:00:00Z" --single-events true --order-by startTime
# Get a specific event
gws calendar events get --calendar-id primary --event-id EVENT_ID
# Quick-add an event (natural language)
gws calendar events quickAdd --calendar-id primary --text "Lunch with Sarah tomorrow at noon"
# Delete an event
gws calendar events delete --calendar-id primary --event-id EVENT_ID
# List all your calendars
gws calendar calendarList list
# Check free/busy
gws calendar freebusy query --json '{
"timeMin": "2026-03-10T00:00:00Z",
"timeMax": "2026-03-10T23:59:59Z",
"items": [{"id": "primary"}]
}'Google Calendar：常用指令
查看行程
# 今天的活動
gws calendar +agenda --today
# 明天的活動
gws calendar +agenda --tomorrow
# 本週
gws calendar +agenda --week
# 未來 3 天
gws calendar +agenda --days 3
# 指定日曆
gws calendar +agenda --today --calendar "Work"
# 表格格式，更易閱讀
gws calendar +agenda --week --format table建立活動
gws calendar +insert \
--summary "Team standup" \
--start "2026-03-10T09:00:00+08:00" \
--end "2026-03-10T09:30:00+08:00" \
--location "Conference Room A" \
--description "Daily sync meeting" \
--attendee alice@example.com \
--attendee bob@example.com時間值必須使用 RFC 3339 格式。請包含時區偏移量（例如 +08:00 代表台北時區）以避免歧義。--attendee 可重複使用以新增多位受邀者。
原始 API 操作
# 列出即將到來的活動
gws calendar events list --calendar-id primary --time-min "2026-03-09T00:00:00Z" --single-events true --order-by startTime
# 取得特定活動
gws calendar events get --calendar-id primary --event-id EVENT_ID
# 快速新增活動（自然語言）
gws calendar events quickAdd --calendar-id primary --text "Lunch with Sarah tomorrow at noon"
# 刪除活動
gws calendar events delete --calendar-id primary --event-id EVENT_ID
# 列出你所有的日曆
gws calendar calendarList list
# 查詢空閒/忙碌狀態
gws calendar freebusy query --json '{
"timeMin": "2026-03-10T00:00:00Z",
"timeMax": "2026-03-10T23:59:59Z",
"items": [{"id": "primary"}]
}'Security Checklist
Before you start using gws daily, walk through this checklist:
1. Minimal Scope Principle
Only request the scopes you need. For Gmail + Calendar only:
gws auth login -s gmail,calendarIf you later need additional services, you can re-login with broader scopes. But start narrow.
2. Keep OAuth App in Testing Mode
Do not publish your OAuth app. Testing mode limits it to designated test users (you), which is exactly what you want for personal use. A published app with overly broad scopes is a much larger target.
3. Protect Your Credential Files
# Ensure correct permissions
chmod 600 ~/.config/gws/client_secret.json
chmod 700 ~/.config/gws/
# Verify
ls -la ~/.config/gws/4. Never Commit Credentials to Git
Add to your global .gitignore:
echo "client_secret*.json" >> ~/.gitignore_global
echo "credentials.json" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global5. Review Token Storage
gws auth login stores encrypted credentials using your OS keyring. This is the recommended method. Avoid the plaintext fallback (~/.config/gws/credentials.json) unless you have no other choice.
If you must use plaintext credentials (e.g., headless server):
# Export credentials
gws auth export --unmasked > credentials.json
# Set restrictive permissions immediately
chmod 600 credentials.json
# Use via environment variable
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json6. Revoke Access When Done
If you stop using gws or suspect credential compromise:
# Revoke from CLI
gws auth revoke
# Additionally, revoke from Google Account
# Visit: https://myaccount.google.com/permissions7. Environment Variable Awareness
Be aware that environment variables override stored credentials:
| Variable | Risk |
|---|---|
GOOGLE_WORKSPACE_CLI_TOKEN | Anyone who can read your env can impersonate you |
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE | Points to credential file — protect the path |
Do not set these in shared .bashrc or .zshrc files on multi-user systems. Use a .env file with chmod 600 if needed.
8. Understand What's Pre-v1.0
This project is one week old (created March 2, 2026) with 16,000+ stars. High community interest does not equal maturity. Expect:
- Breaking changes between versions
- Potential bugs in edge cases
- No guaranteed security audit has been performed
- Rapid release cadence (multiple releases per week)
Recommendation: Pin your version and update intentionally, not automatically.
# Pin a specific version with npm
npm install -g @googleworkspace/cli@0.8.1安全檢查清單
在你開始每天使用 gws 之前，逐項確認以下清單：
1. 最小範圍原則
只請求你需要的權限範圍。如果只用 Gmail + Calendar：
gws auth login -s gmail,calendar如果之後需要額外的服務，你可以用更廣的範圍重新登入。但一開始請從最窄的範圍開始。
2. 保持 OAuth 應用程式在 Testing 模式
不要發布你的 OAuth 應用程式。Testing 模式將其限制在指定的測試使用者（也就是你），這正是個人使用所需要的。一個發布的、擁有過廣範圍的應用程式會是更大的攻擊目標。
3. 保護你的憑證檔案
# 確保正確的權限
chmod 600 ~/.config/gws/client_secret.json
chmod 700 ~/.config/gws/
# 驗證
ls -la ~/.config/gws/4. 絕不將憑證提交到 Git
加入你的全域 .gitignore：
echo "client_secret*.json" >> ~/.gitignore_global
echo "credentials.json" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global5. 檢查 Token 儲存方式
gws auth login 使用你的作業系統金鑰鏈儲存加密憑證。這是推薦的方式。除非沒有其他選擇，否則避免使用明文備援方式（~/.config/gws/credentials.json）。
如果你必須使用明文憑證（例如無介面的伺服器）：
# 匯出憑證
gws auth export --unmasked > credentials.json
# 立即設定嚴格權限
chmod 600 credentials.json
# 透過環境變數使用
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json6. 不再使用時撤銷存取
如果你停止使用 gws 或懷疑憑證洩漏：
# 從 CLI 撤銷
gws auth revoke
# 同時從 Google 帳號撤銷
# 前往：https://myaccount.google.com/permissions7. 環境變數意識
注意環境變數會覆蓋已儲存的憑證：
| 變數 | 風險 |
|---|---|
GOOGLE_WORKSPACE_CLI_TOKEN | 任何能讀取你環境變數的人都能冒充你 |
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE | 指向憑證檔案——保護好路徑 |
不要在多使用者系統的共用 .bashrc 或 .zshrc 中設定這些變數。如有需要，使用 chmod 600 保護的 .env 檔案。
8. 理解 Pre-v1.0 的意義
這個專案只有一週大（2026 年 3 月 2 日建立），有超過 16,000 顆星。高度的社群關注不等於成熟度。請預期：
- 版本間的破壞性變更
- 邊緣情境的潛在 bug
- 沒有經過保證的安全審計
- 快速的釋出節奏（每週多個版本）
建議： 鎖定你的版本，有意識地更新，而非自動更新。
# 用 npm 鎖定特定版本
npm install -g @googleworkspace/cli@0.8.1Quick Reference Card
Gmail
| Task | Command |
|---|---|
| Send email | gws gmail +send --to EMAIL --subject SUBJ --body TEXT |
| Inbox triage | gws gmail +triage |
| Unread from specific sender | gws gmail +triage --query "from:name@example.com" |
| Watch for new emails | gws gmail +watch |
| List labels | gws gmail users labels list --user-id me |
| Trash a message | gws gmail users messages trash --user-id me --id ID |
Calendar
| Task | Command |
|---|---|
| Today's agenda | gws calendar +agenda --today |
| This week's agenda | gws calendar +agenda --week |
| Create event | gws calendar +insert --summary TEXT --start TIME --end TIME |
| Quick-add (natural language) | gws calendar events quickAdd --calendar-id primary --text "..." |
| List calendars | gws calendar calendarList list |
| Delete event | gws calendar events delete --calendar-id primary --event-id ID |
Auth
| Task | Command |
|---|---|
| Login (minimal scopes) | gws auth login -s gmail,calendar |
| Check status | gws auth status |
| Revoke access | gws auth revoke |
| Export credentials | gws auth export --unmasked |
快速參考卡
Gmail
| 任務 | 指令 |
|---|---|
| 寄送郵件 | gws gmail +send --to EMAIL --subject SUBJ --body TEXT |
| 收件匣整理 | gws gmail +triage |
| 特定寄件人的未讀 | gws gmail +triage --query "from:name@example.com" |
| 監聽新郵件 | gws gmail +watch |
| 列出標籤 | gws gmail users labels list --user-id me |
| 將訊息移至垃圾桶 | gws gmail users messages trash --user-id me --id ID |
Calendar
| 任務 | 指令 |
|---|---|
| 今日行程 | gws calendar +agenda --today |
| 本週行程 | gws calendar +agenda --week |
| 建立活動 | gws calendar +insert --summary TEXT --start TIME --end TIME |
| 快速新增（自然語言） | gws calendar events quickAdd --calendar-id primary --text "..." |
| 列出日曆 | gws calendar calendarList list |
| 刪除活動 | gws calendar events delete --calendar-id primary --event-id ID |
認證
| 任務 | 指令 |
|---|---|
| 登入（最小範圍） | gws auth login -s gmail,calendar |
| 檢查狀態 | gws auth status |
| 撤銷存取 | gws auth revoke |
| 匯出憑證 | gws auth export --unmasked |
Known Issues Worth Watching
As of v0.8.1 (March 2026):
- No multi-account support — you can only be logged into one Google account at a time (#293)
- Testing-mode OAuth apps limited to ~25 scopes — the
recommendedpreset has 85+ and will fail. Use-s gmail,calendarto avoid this - Windows npm install issues —
gws.exemay not be correctly placed in PATH (#306) - Scope selection problems — some services don't correctly request their required scopes during
auth login(#310) - Non-collaborator PRs are temporarily disabled — community contributions are limited to issues and discussions
Follow the GitHub releases page for updates and breaking change notices.
值得關注的已知問題
截至 v0.8.1（2026 年 3 月）：
- 不支援多帳號 —— 你一次只能登入一個 Google 帳號（#293）
- Testing 模式的 OAuth 應用程式限制約 25 個範圍 ——
recommended預設有超過 85 個，會導致失敗。使用-s gmail,calendar來避免這個問題 - Windows npm 安裝問題 ——
gws.exe可能未被正確放入 PATH（#306） - 範圍選擇問題 —— 某些服務在
auth login時不能正確請求它們所需的範圍（#310） - 暫時停用非協作者的 PR —— 社群貢獻目前限於 issue 和 discussion
關注 GitHub releases 頁面 以獲取更新和破壞性變更通知。
Summary
gws is a powerful tool that brings Gmail and Google Calendar to your terminal. The key takeaways:
- Install via npm — simplest path, no Rust required
- Always use
-s gmail,calendarwhen logging in — minimal scopes protect you - Keep your OAuth app in Testing mode — don't publish it
- Use helper commands (
+send,+triage,+agenda,+insert) for daily tasks - Fall back to raw API commands for advanced operations
- Pin your version — this is pre-v1.0 software
- Revoke access if you stop using it or suspect compromise
The tool is young but promising. Use it with awareness of its maturity level, and it can genuinely streamline your email and calendar workflows without leaving the terminal.
總結
gws 是一個強大的工具，將 Gmail 和 Google Calendar 帶入你的終端機。關鍵要點：
- 透過 npm 安裝 —— 最簡單的方式，不需要 Rust
- 登入時務必使用
-s gmail,calendar—— 最小範圍保護你 - 保持 OAuth 應用程式在 Testing 模式 —— 不要發布它
- 使用輔助指令（
+send、+triage、+agenda、+insert）處理日常任務 - 進階操作退回使用原始 API 指令
- 鎖定版本 —— 這是 pre-v1.0 的軟體
- 停止使用或懷疑洩漏時撤銷存取
這個工具年輕但前途看好。在理解其成熟度的前提下使用，它確實能在不離開終端機的情況下，大幅優化你的電子郵件和日曆工作流程。