DEV Community

Cover image for كيفية استخدام Google Workspace CLI والاستفادة منه
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام Google Workspace CLI والاستفادة منه

#cli #google #productivity #tutorial

تُعد أداة سطر الأوامر (CLI) الخاصة بـ Google Workspace (المعروفة باسم gws) أداة ديناميكية مفتوحة المصدر تتيح للمطورين والعملاء الذكاء الاصطناعي تحكمًا مباشرًا وموحدًا في خدمات Google Workspace مثل Drive وGmail وCalendar وSheets وDocs وChat وAdmin وجميع واجهات برمجة التطبيقات (API) الأخرى. تعتمد الأداة على خدمة Discovery Service الحية من Google، مما يضمن أن كل أمر يبقى محدثًا دون الحاجة لتحديثات يدوية أو تغييرات في الكود. يمكنك تثبيت Google Workspace CLI عالميًا عبر npm، المصادقة مرة واحدة باستخدام OAuth، وربطها بعملاء مثل Claude Code أو Cursor بمهارات مدمجة. لا مزيد من التدفقات المعقدة أو تعدد الحزم.

جرّب Apidog اليوم

ما هو Google Workspace CLI ولماذا تحتاجه؟

إذا كنت مطورًا أو مسؤول أنظمة وتريد أتمتة خدمات Google Workspace (مثل إدارة ملفات Drive، إرسال Gmail، أحداث Calendar، التعديل على Sheets أو Docs أو النشر في Chat)، ستواجه غالبًا تعقيدات في كتابة سكريبتات curl، إدارة OAuth يدوياً، وتركيب عدة SDKs لكل خدمة.

Google Workspace CLI يحل هذه المشكلة بأداة واحدة تدعم جميع واجهات برمجة التطبيقات بشكل ديناميكي. الأوامر تبقى حديثة دومًا، بدون تكرار الكود أو مشاكل التوافق عند تحديث Google API.

مميزات سريعة:

  • إخراج JSON نظيف وقابل للبرمجة.
  • تشغيل تجريبي (dry-run) لأي أمر.
  • ترقيم صفحات تلقائي وسهل.
  • اختصارات (أكثر من 40) مثل gws gmail +send أو gws calendar +agenda.
  • مهارات عميل جاهزة للدمج مع أدوات الذكاء الاصطناعي مثل Claude Code أو Cursor.

تكامل مع Apidog: إذا كنت تبني أو تختبر تكاملات APIs مع أتمتة Workspace، استخدم Apidog كعميل API مجاني لإرسال الطلبات، فحص الاستجابات، إدارة البيئات وتشغيل مجموعات الاختبار.

تثبيت Google Workspace CLI

المتطلب الأساسي: Node.js إصدار 18 أو أحدث.

تحقق من الإصدار:

node --version
Enter fullscreen mode Exit fullscreen mode

التشغيل الفوري عبر npx

للاختبار السريع أو السكريبتات لمرة واحدة:

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

التثبيت العالمي

للاستخدام الدائم:

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

الأداة تأتي بثنائيات جاهزة، فلا داعي لتجميع Rust محليًا. متاحة أيضًا عبر GitHub Releases أو Homebrew (brew install googleworkspace/cli) أو Nix.

إعداد Google Workspace CLI لعملاء الذكاء الاصطناعي

شغل الأمر التالي للإعداد والمصادقة:

gws auth setup
Enter fullscreen mode Exit fullscreen mode
  • سيفتح متصفحك لإنشاء مشروع Google Cloud إذا لزم الأمر، تفعيل APIs المطلوبة، وتخزين بيانات الاعتماد مشفرة وآمنة.

تثبيت مهارات العميل

بعد الإعداد:

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

أو استخدم أدوات التثبيت الخاصة بالعميل (مثل Claude Code أو Cursor). أعد تشغيل عميلك ليتمكن من اكتشاف أوامر gws تلقائيًا.

إعداد مشروع فقط (وليس عالمي) 

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

إدارة المصادقة

  • إعادة تسجيل الدخول أو تبديل الحسابات: 
  gws auth login
Enter fullscreen mode Exit fullscreen mode
  • التحقق من المستخدم الحالي والنطاقات: 
  gws auth whoami
Enter fullscreen mode Exit fullscreen mode
  • تسجيل الخروج: 
  gws auth logout
Enter fullscreen mode Exit fullscreen mode
  • تصدير بيانات الاعتماد للاستخدام في CI أو بدون واجهة رسومية: 
  gws auth export --unmasked > creds.json
  export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json
Enter fullscreen mode Exit fullscreen mode
  • إعادة استخدام رموز gcloud: 
  export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
Enter fullscreen mode Exit fullscreen mode

تعطيل القياس عن بعد (Telemetry) 

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1
Enter fullscreen mode Exit fullscreen mode

أوامر Google Workspace CLI: أمثلة عملية

الأوامر تكتشف ديناميكيًا، استخدم:

gws --help
Enter fullscreen mode Exit fullscreen mode

لرؤية جميع الخدمات.

إدارة Drive

  • قائمة الملفات الحديثة (بحث بالاسم): 
  gws drive files list --params '{"pageSize":10, "q":"name contains report"}'
Enter fullscreen mode Exit fullscreen mode
  • رفع ملف: 
  gws drive +upload ./budget.xlsx --name "2026 Budget"
Enter fullscreen mode Exit fullscreen mode

Gmail

  • إرسال بريد: 
  gws gmail +send --to colleague@example.com --subject "Update" --body "See attached." --attach ./file.pdf
Enter fullscreen mode Exit fullscreen mode
  • الرد أو تصنيف البريد الوارد: 
  gws gmail +reply --message-id <ID> --body "Thanks!"
  gws gmail +triage
Enter fullscreen mode Exit fullscreen mode

Calendar

  • إنشاء حدث: 
  gws calendar +insert --summary "Sprint Planning" --start "2026-03-20T10:00" --end "2026-03-20T11:00" --attendees "team@example.com"
Enter fullscreen mode Exit fullscreen mode
  • عرض جدول اليوم: 
  gws calendar +agenda --today
Enter fullscreen mode Exit fullscreen mode

Sheets

  • إضافة صف: 
  gws sheets +append --spreadsheetId <ID> --range "Sheet1!A:C" --values "Task X,Done,2026-03-16"
Enter fullscreen mode Exit fullscreen mode

Docs

  • إدراج نص: 
  gws docs +write --documentId <ID> --text "New section added via Google Workspace CLI"
Enter fullscreen mode Exit fullscreen mode

Chat

  • نشر رسالة: 
  gws chat +send --space <SPACE_ID> --text "Deployment complete 🚀"
Enter fullscreen mode Exit fullscreen mode

استخدم --dry-run لمعاينة استدعاء API دون التنفيذ، و--page-all للترقيم الكامل بصيغة NDJSON.

خيارات وتكوينات متقدمة

  • حفظ الإعدادات العامة بمتغيرات البيئة أو ملف .env: 
  export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'
Enter fullscreen mode Exit fullscreen mode
  • ضبط المهلات، تنسيق الإخراج (--json, --yaml)، أو فرض استخدام سلسلة مفاتيح معينة.
  • عرض التكوين الحالي: 
  gws config
Enter fullscreen mode Exit fullscreen mode

الدمج مع عملاء الذكاء الاصطناعي والموجهات

بعد تثبيت المهارات، يمكن للعملاء استدعاء gws مباشرة.

نمط "use gws" في الموجهات:

  • "List my recent Drive files using Google Workspace CLI"
  • "Send a follow-up email via Google Workspace CLI"

قاعدة الاستدعاء التلقائي:
أضف لتعليمات الوكيل (مثل CLAUDE.md أو قواعد Cursor):

"كلما تضمنت المهمة Gmail أو Drive أو Calendar أو Sheets أو Docs أو Chat، استخدم أوامر Google Workspace CLI تلقائيًا قبل الرد. قم بحل الخدمة والطريقة أولاً."

دمجه مع Apidog لاختبار واجهات البرمجة بثقة

Google Workspace CLI يمنحك وصولاً مباشرًا، لكن عند اختبار الحمولات أو الاستجابات أو النطاقات استخدم Apidog كعميل API متكامل ومرئي.

حالات استخدام عملية:

  • تحقق من الحمولة الدقيقة لـ Sheets.values.append في Apidog قبل إضافتها تلقائيًا.
  • استكشاف أخطاء Gmail (النطاقات أو الاستجابات) عبر بناء الطلبات وتشغيلها بصريًا.
  • تخزين رموز OAuth أو مفاتيح الخدمة كمتغيرات في Apidog لاختبار الحسابات المختلفة.

Google Workspace CLI + Apidog = أتمتة + اختبار API موثوق.

الأسئلة الشائعة

هل يرسل Google Workspace CLI بياناتي خارجيًا؟

الأداة لا تجري أي مكالمات خارجية مباشرة. بياناتك تبقى داخل حساب Google الخاص بك.

ما هي الخدمات المدعومة؟

كل API لـ Workspace يتم اكتشافه ديناميكيًا: Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Script وغيرها.

هل الأوامر تبقى حديثة؟

نعم. الأداة تستعلم خدمة Discovery Service مباشرة، وتضيف الطرق الجديدة تلقائيًا.

هل أحتاج مفتاح API؟

لا. الاعتماد على OAuth القياسي أو حسابات الخدمة فقط.

ما العملاء المدعومون؟

Claude Code، Cursor، OpenClaw، Gemini CLI، VS Code Extensions، وأي أداة تدعم MCP أو Agent Skills.

ما الفرق بين الأوامر الخام والمساعدات (+)؟

الأوامر الخام = استدعاء Discovery API مباشرة (مثل drive.files.list).

الاختصارات + = مهام شائعة (مثل +upload, +send).

هل يمكن استخدام الأداة بدون عميل ذكاء اصطناعي؟

نعم، مثالية للسكريبتات، الأتمتة، أو العمل اليومي عبر الطرفية.

موارد إضافية

Top comments (0)