Gemini API CLI

‫Gemini API CLI (gemini-api) هو برنامج سطر أوامر عديم الحالة ولا يعتمد على أي تبعيات، تم تصميمه لوكلاء الذكاء الاصطناعي الذين لديهم إمكانية الوصول إلى واجهة الأوامر (ويمكن استخدامه من خلال النصوص البرمجية وCI). يمكن بعد ذلك لوكيل الترميز إنشاء نصّ من إنشاء الذكاء الاصطناعي والوسائط وتحليل الملفات وتفويض المهام إلى الوكلاء المُدارين في Gemini. وهي متوافقة مع Antigravity أو Claude Code أو Codex أو Cursor أو OpenClaw أو Hermes أو أي بيئة Shell.

يتم تشغيل كل ميزة كأمر عادي في واجهة الأوامر على Interactions API. يمكنك تشغيل الأوامر نفسها من عملية فرعية للوكيل أو من الوحدة الطرفية أو من مسار CI:

# 1. Install on macOS or Linux
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

# 2. Set your API key
export GEMINI_API_KEY="YOUR_API_KEY"

# 3. Generate media, analyze a file, or launch a background managed agent
gemini-api image "Minimalist isometric icon of a cloud database" --out ./assets/db-icon.jpg
gemini-api analyze -i ./docs/quarterly-report.pdf "Summarize the key findings in three bullets."
gemini-api agent run "Compare WebRTC SFU architectures and cite sources" \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false

اختيار أداة Gemini المناسبة

يمكنك استخدام gemini-api عندما يحتاج وكيل أو نص برمجي إلى استدعاء Gemini مباشرةً من shell بدون إضافة رمز حزمة تطوير البرامج (SDK) إلى مشروعك. استخدِم حِزم تطوير البرامج (SDK) وإعداد وكيل الترميز عند دمج Gemini في تطبيق:

آلية العمل

غالبًا ما تتسبب طلبات REST الأولية وواجهات سطر الأوامر التفاعلية في حدوث مشاكل لوكلاء الترميز. تستهلك وسائط Base64 نافذة السياق، وتمنع الطلبات التفاعلية العمليات الفرعية، وتؤدي بيانات التدريب القديمة إلى ظهور إشارات خاطئة.

تضمن أربعة خيارات تصميم موثوقية gemini-api لموظفي الدعم:

• البحث عن المخطّط بلا إنترنت: يمكنك تمرير --usage لطباعة شجرة الأوامر (في KDL)، أو --schema لطباعة مخطّط JSON لطلبات --body.
• الملفات على القرص والمسارات على stdout: تكتب أوامر الوسائط وتحويل الصوت إلى نص الملفات على القرص وتطبع مسار الإخراج فقط، ما يحافظ على البيانات الثنائية خارج السياق.
• عمليات التشغيل التجريبي والمخرجات المنظَّمة: تتحقّق أداة --dry-run من صحة المدخلات، وتخفي بيانات الاعتماد، وتُجري معاينة لطلب HTTP بلا اتصال بالإنترنت. يمكنك تمرير -o json أو -o toon أو --jq للحصول على مخرجات يمكن معالجتها آليًا. أضِف --agent-mode لعرض أخطاء JSON المنظَّمة في stderr، وتحقَّق من رموز الخروج لمعالجة حالات الفشل. لا تطلب الأوامر مطلقًا إدخال بيانات إلا إذا تم تمرير --interactive.
• عدم الاحتفاظ بالبيانات تلقائيًا: لا تحتفظ الأوامر بأي حالة محلية مخفية. يمكنك ربط المهام المتعدّدة الخطوات بشكل صريح باستخدام --previous-interaction-id أو معرّف موارد منتظم (URI) لـ files/<id> تم تحميله أو معرّف تفاعل في الخلفية.

-o json: لا تزال أوامر الوسائط تكتب الملف على القرص وتطبع البيانات الوصفية إلى stdout:

{
  "kind": "image",
  "mime_type": "image/jpeg",
  "path": "/path/to/project/assets/db-icon.jpg",
  "response_id": "v1_...",
  "size_bytes": 2914159,
  "status": "completed"
}

البدء

ثبِّت واجهة سطر الأوامر، وأضِف gemini-api إلى PATH، واضبط GEMINI_API_KEY، وأضِف قواعد الاستخدام إلى وكيل الترميز.

1. تثبيت الملف الثنائي

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=<release-tag> bash

iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex

go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest

2. ضبط إعدادات المصادقة والتحقّق منها

أنشئ مفتاح واجهة برمجة تطبيقات في Google AI Studio (راجِع مفاتيح واجهة برمجة التطبيقات). اضبط GEMINI_API_KEY في واجهة الأوامر وبيئة العملية الفرعية للوكيل:

export GEMINI_API_KEY="YOUR_API_KEY"

على محطة عمل محلية، يمكنك حفظ المفتاح في سلسلة مفاتيح نظام التشغيل (سلسلة مفاتيح macOS أو خدمة Linux Secret Service أو Windows Credential Manager). مرِّر --no-keyring لتخزين المفتاح في ~/.config/gemini-api/config.yaml بدلاً من ذلك:

# Save to your OS keychain (or run gemini-api configure --interactive)
gemini-api configure --api-key "YOUR_API_KEY"

# Check the active credential source, then preview a request offline
gemini-api whoami
gemini-api generate "Confirm CLI setup in one sentence." --dry-run

3- إعطاء التعليمات للوكيل

يمكنك إضافة هذا المقتطف إلى AGENTS.md أو CLAUDE.md أو .cursorrules أو الطلب الموجَّه إلى النظام في مشروعك ليعرف وكيل الترميز كيفية استخدام gemini-api:

## Gemini API CLI (`gemini-api`)

You have access to `gemini-api` through the shell. Use it to generate text or media (images, speech, music, video), analyze documents and recordings, or run and manage Gemini managed agents.

1. Run `gemini-api --help` or `gemini-api --usage` to choose a command, and `gemini-api <command> --schema` before building a `--body` JSON payload.
2. Preview unfamiliar or complex calls offline with `--dry-run -o json`.
3. For a single JSON result or `--jq` filtering on `generate` or `agent run`, pass `--stream=false -o json`.
4. To chain multi-step workflows, capture the output paths that media and transcription commands print to stdout, and the `id` values returned by `generate` or `agent run`.

بعد ذلك، وجِّه طلبًا إلى وكيل الترميز كالمعتاد:

Build a landing page for our developer tool. Use Gemini to generate a hero
illustration and a 15-second welcome voiceover, and start a background Deep
Research agent to compare competing CLI onboarding flows. Wire the assets and
findings into the page.

الطلبات الصوتية

يمكنك تشغيل gemini-api --help لعرض جميع الطلبات، أو gemini-api explore لتصفّحها بشكل تفاعلي.

Workflows

يستخدم كل أمر تلقائيًا نموذجًا مناسبًا لمهمته. مرِّر "--model" (-m) لاختيار نموذج مختلف. شغِّل gemini-api models لعرض الخيارات المتاحة.

إنشاء الصور وتعديلها

يمكن للوكلاء الذين ينشئون واجهات مستخدم للويب أو الأجهزة الجوّالة إنشاء عناصر نائبة ورموز وصور رئيسية باستخدام Nano Banana. يمكنك تمرير مسار تم إنشاؤه مرة أخرى باستخدام -i لتعديل الصورة:

# Generate a 16:9 image at 2K resolution (512, 1K, 2K, or 4K) and capture its path
HERO_PATH=$(gemini-api image "Friendly robot mascot in a sunlit workshop, space on left for headline" \
  --aspect-ratio 16:9 \
  --image-size 2K \
  --out ./public/images/hero.jpg)

# Edit the generated image
gemini-api image "Add a winter scarf and soft snowfall outside the window" \
  -i "$HERO_PATH" \
  --out ./public/images/hero-winter.jpg

يمكنك تمرير -i عدة مرات لدمج الصور المرجعية، مثل شخصية ودليل أسلوب.

تركيب الكلام

يُنشئ gemini-api tts ملفات صوتية بتنسيق WAV وبتردد 24 كيلوهرتز لإشارات واجهة المستخدم ومعاينات تسهيل الاستخدام والأدلة الإرشادية الصوتية. الصوت التلقائي هو Kore، ويمكنك اختيار صوت آخر باستخدام --voice. بالنسبة إلى الحوار بين متحدّثَين، يجب تصنيف كل دور في الطلب وربط المتحدّثين بالأصوات:

gemini-api tts "Build succeeded. All integration tests passed." \
  --voice Aoede \
  --out ./public/audio/build-ok.wav

gemini-api tts "Alice: Welcome to the release walkthrough! Bob: Let's look at what shipped today." \
  --multi-speaker "Alice=Kore,Bob=Puck" \
  --out ./public/audio/release-intro.wav

موسيقى وفيديو

ألِّف مقاطع موسيقية أصلية باستخدام Lyria، وأنشِئ مقاطع MP4 باستخدام Gemini Omni:

gemini-api music "Warm ambient synth and acoustic guitar background loop, 95 BPM" \
  --out ./public/audio/bg-loop.mp3

gemini-api video "A drone shot of a mountain landscape at sunrise." \
  --aspect-ratio 16:9 \
  --resolution 1080p \
  --out ./public/video/mountain-sunrise.mp4

بشكل تلقائي، ينتظر الأمر video انتهاء عملية الإنشاء ويكتب ملف MP4 على القرص. مرِّر --async لعرض معرّف التفاعل على الفور، ثم شغِّل gemini-api video --resume <id> --out <path> لاحقًا. مرِّر -i لإضافة مؤثرات حركية إلى صورة حالية.

إنشاء النص

‫gemini-api generate يرسل نصًا إلى stdout:

gemini-api generate "Write a one-paragraph welcome message for new users of a note-taking app."

أضِف --stdin لإدخال النص في الطلب. يمكنك تمرير --previous-interaction-id لمواصلة تفاعل سابق.

تحليل المستندات وتحويل الصوت إلى نص

يجيب "analyze" عن الأسئلة المتعلقة بملفات PDF وجداول البيانات ولقطات الشاشة والملفات الصوتية وملفات الفيديو وعناوين URL العلنية على YouTube. يكتب "transcribe" نصًا منسقًا (md أو text أو json أو srt) على القرص:

gemini-api analyze -i ./docs/product-brief.pdf "List the open questions and who owns each one." > open-questions.md

gemini-api transcribe -i ./fixtures/customer-call.mp4 --format srt --out ./fixtures/customer-call.srt

يمكنك تمرير -i عدة مرات إلى analyze لمقارنة الملفات، مثل لقطات الشاشة قبل وبعد.

يرسل gemini-api الملفات المحلية المضمّنة التي يصل حجمها إلى 14 ميغابايت (20 ميغابايت بعد ترميز base64). بالنسبة إلى الملفات الأكبر حجمًا، يمكنك تحميلها مرة واحدة باستخدام files upload --wait وإعادة استخدام معرّف الموارد المنتظم (URI) الذي تم عرضه files/<id>:

FILE_URI=$(gemini-api files upload ./recordings/all-hands.mp4 --wait)

gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format json --out ./recordings/all-hands.json

تشغيل الوكلاء وإدارتهم

يمكن لوكيل الترميز تفويض مهام البحث المتعددة الخطوات أو المهام في وضع الحماية إلى وكلاء مُدارين من Gemini، مثل وكيل Deep Research. يمكنك تمرير --background --stream=false للحصول على معرّف تفاعل على الفور بدلاً من إبقاء البث مفتوحًا:

# Launch a Deep Research job in the background and capture its interaction ID
RESEARCH_ID=$(gemini-api agent run "Compare open-source vector index benchmarks and cite primary papers." \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false \
  --jq '.id')

# Check status or fetch the finished result while continuing other work
gemini-api agent status "$RESEARCH_ID" -o json

شغِّل gemini-api agent cancel <id> لإيقاف مهمة قيد التشغيل. يمكنك أيضًا تشغيل وكيل Antigravity في وضع حماية عن بُعد باستخدام agent run، أو إدارة الوكلاء المخصّصين باستخدام agent create وlist وget وdelete. يُرجى الاطّلاع على البيئات لضبط وضع الحماية الخاص بالوكيل.

نصوص الطلبات المخصّصة

بالنسبة إلى الخيارات التي لا تتضمّن علامات مخصّصة، يمكنك تمرير حمولة JSON أولية من Interactions API مع --body (مضمّنة أو كـ @file.json). يمكنك تمرير --body لضبط مخططات response_format أو أدوات استدعاء الدوال أو generation_config أو "store": false. يُرجى تشغيل gemini-api <command> --schema أولاً للتحقّق من الحقول الصالحة:

# Inspect the JSON Schema for the request body
gemini-api generate --schema > generate-schema.json

# Return schema-constrained JSON and skip storing the interaction
cat logs.txt | gemini-api generate "Extract every error message from these logs." \
  --stdin \
  --body '{
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {"errors": {"type": "array", "items": {"type": "string"}}},
        "required": ["errors"]
      }
    },
    "store": false
  }'

يتم دمج --body مع علامات الأوامر. إذا تم ضبط المفتاح نفسه في كليهما، سيتعذّر تنفيذ الأمر مع رمز الخروج 2، وبالتالي ستتعذّر المدخلات المتعارضة بسرعة.

رموز الخروج

يعرض كل أمر رمز خروج مكتوبًا حتى تتمكّن النصوص البرمجية والوكلاء من معالجة الأخطاء بدون تحليل نص الخطأ. على سبيل المثال، يشير الرمز 3 إلى مشكلة في المصادقة، بينما يشير الرمز 2 إلى بنية أمر غير صالحة:

يمكنك تشغيل gemini-api --help-global لعرض العلامات العامة التي يشاركها كل أمر (المصادقة والإخراج والشبكة والتشخيص).

القيود

• تتطلّب أوامر البث (generate وagent run) استخدام --stream=false عند دمجها مع -o json أو --jq لعرض عنصر استجابة JSON واحد.
• يبلغ الحد الأقصى لملفات -i المضمّنة في الطلب 14 ميغابايت من بيانات الملفات الأولية (20 ميغابايت من حمولة الطلب، بما في ذلك ترميز base64). يمكنك تحميل ملفات كبيرة باستخدام gemini-api files upload. تحذف Files API الملفات المحمَّلة بعد 48 ساعة.
• يتيح gemini-api طلبات HTTP العادية، وبث SSE، والاستطلاع غير المتزامن، وليس WebSockets ثنائية الاتجاه. لبث الصوت والفيديو في الوقت الفعلي، استخدِم Live API مع حِزم تطوير البرامج (SDK) الخاصة بـ Google GenAI.

الخطوات التالية

• إعداد وكيل الترميز
• Interactions API
• الوكلاء المُدارون في Gemini
• ‫gemini-api-cli على GitHub