DEV Community

Cover image for Hướng Dẫn Sử Dụng Google Workspace CLI Hiệu Quả
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng Dẫn Sử Dụng Google Workspace CLI Hiệu Quả

#api #cli #google #tutorial

Google Workspace CLI

Google Workspace CLI (gws) là công cụ dòng lệnh mã nguồn mở giúp truy cập thống nhất vào các API của Google Workspace như Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin... mà không cần quản lý nhiều SDK, phạm vi OAuth hay viết các đoạn curl phức tạp. CLI này xây dựng trực tiếp từ Discovery Service của Google nên các lệnh luôn cập nhật, không cần cài đặt lại khi có API mới. Bạn chỉ cần xác thực một lần với OAuth và có thể tích hợp với các tác nhân AI như Claude Code, Cursor, v.v.

Dùng thử Apidog ngay hôm nay

Lợi ích của Google Workspace CLI

Các API của Google Workspace mạnh mẽ nhưng phân mảnh, mỗi dịch vụ lại có endpoint, xác thực và đặc thù riêng. Google Workspace CLI hợp nhất các thao tác này, giảm thiểu việc cập nhật mã nguồn khi API thay đổi và cho phép bạn tự động hóa hoặc truy vấn dữ liệu Workspace một cách dễ dàng, nhất quán.

  • Tập lệnh luôn cập nhật: CLI tự động khám phá các phương thức API mới.
  • Kết quả JSON rõ ràng: Dễ dàng tích hợp với các tác vụ tự động hoặc các tác nhân AI.
  • Hỗ trợ hơn 40 phím tắt: Ví dụ: gws gmail +send, gws calendar +agenda.
  • Có các kỹ năng (skills) sẵn cho các tác nhân: Claude Code, Cursor, OpenClaw, Gemini CLI, v.v.

Nếu bạn cần xác minh các lệnh gọi API, Apidog là ứng dụng khách API miễn phí giúp gửi request, kiểm tra response, quản lý môi trường OAuth, và chạy kiểm thử.

1. Cài đặt Google Workspace CLI

Yêu cầu: Node.js >= 18

Kiểm tra phiên bản Node.js của bạn:

node --version
Enter fullscreen mode Exit fullscreen mode

Chạy nhanh với npx (không cần cài đặt)

Dùng thử CLI ngay mà không cần cài đặt toàn cục:

npx @googleworkspace/cli --help
npx @googleworkspace/cli drive files list --params '{"pageSize":1}'
Enter fullscreen mode Exit fullscreen mode

Thích hợp cho các kiểm thử nhanh hoặc script dùng một lần.

Cài đặt toàn cục

Để sử dụng thường xuyên, cài đặt toàn cục:

npm install -g @googleworkspace/cli
gws --version
Enter fullscreen mode Exit fullscreen mode

CLI đóng gói nhị phân sẵn, khởi động nhanh, không yêu cầu biên dịch Rust. Ngoài npm, bạn có thể tải nhị phân từ GitHub Releases, dùng Homebrew (brew install googleworkspace/cli) hoặc Nix.

2. Thiết lập Google Workspace CLI cho tác nhân lập trình AI

Chạy lệnh sau để thiết lập dự án, bật API và xác thực OAuth:

gws auth setup
Enter fullscreen mode Exit fullscreen mode

Trình duyệt sẽ mở ra để xác thực. Thông tin xác thực lưu trữ an toàn trong keyring hệ điều hành (AES-256-GCM).

Cài đặt kỹ năng tác nhân

Sau khi setup, cài skills cho tác nhân:

npx skills add https://github.com/googleworkspace/cli
Enter fullscreen mode Exit fullscreen mode

Hoặc chạy trình cài đặt riêng cho Claude Code, Cursor, v.v. Khởi động lại tác nhân để nhận lệnh gws.

Thiết lập cho từng project

Để cấu hình riêng cho từng dự án:

gws auth setup --project
Enter fullscreen mode Exit fullscreen mode

Xác thực và chuyển đổi tài khoản

  • Đăng nhập lại hoặc chuyển tài khoản: 
  gws auth login
Enter fullscreen mode Exit fullscreen mode
  • Kiểm tra người dùng hiện tại: 
  gws auth whoami
Enter fullscreen mode Exit fullscreen mode
  • Đăng xuất: 
  gws auth logout
Enter fullscreen mode Exit fullscreen mode
  • Dùng trong CI/headless: 
  gws auth export --unmasked > creds.json
  export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json
Enter fullscreen mode Exit fullscreen mode
  • Dùng lại token gcloud: 
  export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
Enter fullscreen mode Exit fullscreen mode

Tắt telemetry 

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1
Enter fullscreen mode Exit fullscreen mode

3. Sử dụng Google Workspace CLI với các lệnh cốt lõi

Chạy gws --help để xem các dịch vụ khả dụng. Một số ví dụ thực tiễn:

Drive

  • Liệt kê file: 
  gws drive files list --params '{"pageSize":10, "q":"name contains report"}'
Enter fullscreen mode Exit fullscreen mode
  • Upload file: 
  gws drive +upload ./budget.xlsx --name "2026 Budget"
Enter fullscreen mode Exit fullscreen mode

Gmail

  • Gửi email: 
  gws gmail +send --to colleague@example.com --subject "Cập nhật" --body "Xem tệp đính kèm." --attach ./file.pdf
Enter fullscreen mode Exit fullscreen mode
  • Trả lời và phân loại: 
  gws gmail +reply --message-id <ID> --body "Cảm ơn!"
  gws gmail +triage
Enter fullscreen mode Exit fullscreen mode

Calendar

  • Tạo sự kiện: 
  gws calendar +insert --summary "Lên kế hoạch Sprint" --start "2026-03-20T10:00" --end "2026-03-20T11:00" --attendees "team@example.com"
Enter fullscreen mode Exit fullscreen mode
  • Lịch trình hôm nay: 
  gws calendar +agenda --today
Enter fullscreen mode Exit fullscreen mode

Sheets

  • Thêm hàng vào sheet: 
  gws sheets +append --spreadsheetId <ID> --range "Sheet1!A:C" --values "Task X,Done,2026-03-16"
Enter fullscreen mode Exit fullscreen mode

Docs

  • Chèn văn bản: 
  gws docs +write --documentId <ID> --text "Phần mới được thêm qua Google Workspace CLI"
Enter fullscreen mode Exit fullscreen mode

Chat

  • Gửi tin nhắn: 
  gws chat +send --space <SPACE_ID> --text "Triển khai hoàn tất 🚀"
Enter fullscreen mode Exit fullscreen mode

Lưu ý:

  • Thêm --dry-run để xem trước lệnh gọi API.
  • Dùng --page-all để phân trang NDJSON toàn bộ dữ liệu.

4. Cấu hình nâng cao & tuỳ chọn toàn cục

Lưu cấu hình bằng biến môi trường hoặc tệp .env:

export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'
Enter fullscreen mode Exit fullscreen mode

Có thể điều chỉnh timeout, định dạng đầu ra (--json, --yaml), ép dùng file keyring. Kiểm tra cấu hình hiện tại:

gws config
Enter fullscreen mode Exit fullscreen mode

5. Tích hợp với tác nhân AI & prompt

Sau khi cài skills, các tác nhân (Claude, Cursor, v.v.) sẽ tự nhận các lệnh Google Workspace CLI.

Ví dụ prompt:

  • "Liệt kê các tệp Drive gần đây của tôi bằng Google Workspace CLI"
  • "Gửi email theo dõi qua Google Workspace CLI"

Quy tắc tự động gọi:

Thêm vào rule/hướng dẫn của tác nhân, ví dụ:

"Bất cứ khi nào tác vụ liên quan đến Gmail, Drive, Calendar, Sheets, Docs hoặc Chat, hãy tự động sử dụng lệnh Google Workspace CLI trước khi phản hồi. Trước tiên hãy giải quyết dịch vụ và phương thức."

Các tác nhân sẽ trả về file path hoặc kết quả JSON, dễ tích hợp vào quy trình tự động hóa.

6. Kết hợp với Apidog để kiểm thử & xác minh API

Google Workspace CLI giúp truy cập API, nhưng khi cần debug payload, scopes hoặc phản hồi, sử dụng Apidog để gửi request, kiểm tra response thô, thiết lập môi trường OAuth và xác nhận hành vi.

Quy trình thực tế:

  • Tác nhân đề xuất thêm vào Sheet → Kiểm tra payload Sheets.values.append trước trong Apidog.
  • Khắc phục phạm vi Gmail → Xây dựng & chạy request qua Apidog.
  • Lưu trữ token OAuth, chuyển đổi tài khoản → Quản lý biến trong Apidog.

Kết hợp Google Workspace CLI + Apidog giúp bạn kiểm thử API lặp lại và truy cập dữ liệu trực tiếp an toàn.

7. Câu hỏi thường gặp

Google Workspace CLI có gửi dữ liệu ra ngoài không?

Không, tất cả lệnh gọi API đều thực hiện trực tiếp tới Google, không gửi dữ liệu ra ngoài.

Hỗ trợ dịch vụ nào?

Tất cả API Workspace: Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Script, v.v. được phát hiện động.

Lệnh luôn cập nhật?

Có, CLI truy vấn Discovery Service trực tiếp, hỗ trợ phương thức mới ngay.

Có yêu cầu API key không?

Không, chỉ cần OAuth của Google hoặc tài khoản dịch vụ.

Hỗ trợ các tác nhân/chỉnh sửa nào?

Claude Code, Cursor, OpenClaw, Gemini CLI, VS Code extension, bất cứ công cụ nào tương thích MCP/Agent Skills.

Khác biệt giữa lệnh thô và phím tắt +?

Lệnh thô = đúng tên Discovery (vd: drive.files.list), phím tắt + = thao tác phổ biến (vd: +upload, +send).

Có thể dùng mà không cần AI agent không?

Hoàn toàn được, dùng tốt cho script, automation hoặc thao tác terminal.

Tài nguyên bổ sung

Top comments (0)