Gemini API CLI

‫Gemini API CLI (gemini-api) یک کلاینت خط فرمان بدون حالت و بدون وابستگی است که برای عامل‌های هوش مصنوعی با دسترسی پوسته ساخته شده است (و از اسکریپت‌ها و CI قابل‌استفاده است). سپس نماینده کدنویسی شما می‌تواند نوشتار و رسانه تولید کند، فایل‌ها را تجزیه‌وتحلیل کند، و تکالیف را به نماینده‌های تحت‌مدیریت Gemini واگذار کند. این ابزار با Antigravity،‏ Claude Code،‏ Codex،‏ Cursor،‏ OpenClaw،‏ Hermes، یا هر محیط پوسته دیگری کار می‌کند.

هر ویژگی به‌عنوان یک فرمان پوسته استاندارد در 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 را مستقیماً از پوسته فراخوانی کند، بدون افزودن کد کیت توسعه نرم‌افزار به پروژه‌تان، از gemini-api استفاده کنید. هنگام ساختن Gemini در یک برنامه، از کیت‌های توسعه نرم‌افزار و راه‌اندازی عامل کدنویسی استفاده کنید:

روش کار

فراخوانی‌های REST خام و CLIهای تعاملی اغلب برای عوامل کدنویسی مشکل ایجاد می‌کنند. Base64 media fills the context window, interactive prompts block subprocesses, and stale training data causes hallucinated flags.

چهار انتخاب طراحی باعث می‌شود gemini-api برای نمایندگان قابل‌اعتماد باشد:

• جستجوی طرح‌واره آفلاین: --usage را برای چاپ درخت فرمان (در KDL) یا --schema را برای چاپ «طرح‌واره JSON» برای درخواست‌های --body ارسال کنید.
• فایل‌های روی دیسک، مسیرهای روی stdout: فرمان‌های رسانه و ترانویسی فایل‌ها را روی دیسک می‌نویسند و فقط مسیر خروجی را چاپ می‌کنند، و داده‌های دودویی را خارج از بافت نگه می‌دارند.
• اجرای آزمایشی و برونداد ساختاریافته: --dry-run ورودی‌ها را اعتبارسنجی می‌کند، اطلاعات کاربری را ویرایش می‌کند، و درخواست HTTP را به‌صورت آفلاین پیش‌نمایش می‌کند. برای خروجی ماشین‌خوانا، -o json،‏ -o toon، یا --jq را ارسال کنید. --agent-mode را اضافه کنید تا خطاهای JSON ساختاریافته در stderr برگردانده شود و کدهای خروج را برای رسیدگی به خرابی‌ها بررسی کنید. فرمان‌ها هرگز پیام‌واره نمی‌دهند مگراینکه --interactive را رد کنید.
• بدون حالت به‌طور پیش‌فرض: فرمان‌ها هیچ حالت محلی پنهانی را حفظ نمی‌کنند. زنجیره کار چندمرحله‌ای به‌طور صریح با --previous-interaction-id، files/<id> URI بارگذاری‌شده، یا شناسه تعامل پس‌زمینه.

با -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"
}

شروع کنید

‫CLI را نصب کنید، gemini-api را در PATH قرار دهید، GEMINI_API_KEY را تنظیم کنید، و قوانین استفاده را به عامل کدنویسی‌تان اضافه کنید.

۱. نصب دودویی

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

۲. پیکربندی اصالت‌سنجی و درستی‌سنجی

کلید میانای API در Google AI Studio ایجاد کنید (کلیدهای میانای API را ببینید). GEMINI_API_KEY را در پوسته و محیط زیرفرایند عاملتان تنظیم کنید:

export GEMINI_API_KEY="YOUR_API_KEY"

در ایستگاه کاری محلی، می‌توانید کلید را در دسته کلید سیستم‌عاملتان (دسته کلید macOS، سرویس مخفی Linux، یا Credential Manager در Windows) ذخیره کنید. برای ذخیره کردن کلید در ~/.config/gemini-api/config.yaml، --no-keyring را ارسال کنید:

# 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

۳. به عاملتان دستورالعمل بدهید

این تکه‌کد را به 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 را اجرا کنید تا آن‌ها را به‌صورت تعاملی مرور کنید.

گردش کار

هر فرمان به‌طور پیش‌فرض به مدلی مناسب برای تکلیف خود اختصاص داده می‌شود. برای انتخاب مدل دیگر، --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 با فرکانس ۲۴ کیلوهرتز را برای نشانه‌های واسط کاربر، پیش‌نمایش‌های دسترس‌پذیری، و راهنماهای گام‌به‌گام با روایت صوتی ترکیب می‌کند. صدای پیش‌فرض 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 قطعه‌های اصیل بسازید و با Gemini Omni کلیپ‌های MP4 تولید کنید:

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، صفحه‌گسترده‌ها، نماگرفت‌ها، فایل‌های صوتی و ویدیویی، و نشانی‌های وب عمومی 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 فایل‌های محلی را به‌صورت درون‌خطی تا ۱۴ مگابایت (۲۰ مگابایت پس‌از کدگذاری base64) ارسال می‌کند. برای فایل‌های بزرگ‌تر، یک‌بار با files upload --wait بارگذاری کنید و از files/<id> URI برگردانده‌شده دوباره استفاده کنید:

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) وقتی با -o json یا --jq ترکیب می‌شوند، به --stream=false نیاز دارند تا یک شیء پاسخ JSON تکی برگردانند.
• ورودی‌های فایل -i به‌خط به ۱۴ مگابایت داده فایل خام (۲ مگابایت بار داده درخواست شامل کدبندی base64) محدود می‌شود. فایل‌های بزرگ را با gemini-api files upload بارگذاری کنید. Files API فایل‌های بارگذاری‌شده را پس‌از ۴۸ ساعت حذف می‌کند.
• ‫gemini-api از درخواست‌های استاندارد HTTP، جاری‌سازی SSE، و نظرسنجی ناهمگام پشتیبانی می‌کند، نه WebSockets دوطرفه. برای جاری‌سازی هم‌زمان صدا و ویدیو، از Live API با Google GenAI SDK استفاده کنید.

قدم بعدی چیست

• راه‌اندازی عامل کدنویسی
• Interactions API
• عامل‌های مدیریت‌شده Gemini
• gemini-api-cli در GitHub