Gemini API CLI

‫Gemini API CLI‏ (gemini-api) הוא לקוח שורת פקודה ללא מצב (stateless) וללא יחסי תלות, שמיועד לסוכני AI עם גישה למעטפת (וניתן להשתמש בו מסקריפטים ומ-CI). אחרי זה, סוכן התכנות יכול ליצור טקסט דינמי מבוסס-AI ומדיה, לנתח קבצים ולהקצות משימות לסוכנים מנוהלים של 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-api כשנציג או סקריפט צריכים להפעיל את Gemini ישירות מהמעטפת בלי להוסיף קוד SDK לפרויקט. כשאתם מפתחים אפליקציה עם Gemini, אתם יכולים להשתמש בערכות ה-SDK ובהגדרת סוכן התכנות:

איך זה עובד

קריאות REST גולמיות וממשקי CLI אינטראקטיביים גורמים לעיתים קרובות לבעיות בסוכני תכנות. מדיה ב-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"
}

שנתחיל?

מתקינים את ה-CLI, מוסיפים את 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. הגדרת אימות ואישור

יוצרים מפתח API ב-Google AI Studio (ראו מפתחות API). מגדירים את GEMINI_API_KEY במעטפת ובסביבת תהליך המשנה של הסוכן:

export GEMINI_API_KEY="YOUR_API_KEY"

בתחנת עבודה מקומית, אתם יכולים לשמור את המפתח בצרור המפתחות של מערכת ההפעלה (macOS Keychain,‏ Linux Secret Service או Windows Credential Manager). כדי לאחסן את המפתח ב-~/.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

3. כאן מוסיפים פרומפט בסיס לסוכן

כדי שהסוכן לתכנות יידע איך להשתמש ב-gemini-api, צריך להוסיף את קטע הקוד הזה להנחיית המערכת, ל-AGENTS.md, ל-CLAUDE.md או ל-.cursorrules של הפרויקט:

## 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 של 24kHz לאותות בממשק המשתמש, לתצוגות מקדימות של נגישות ולהדרכות מדוברות. הקול שמוגדר כברירת מחדל הוא 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 שולח קבצים מקומיים בגודל של עד 14MB (או 20MB אחרי קידוד 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

הפעלה וניהול של סוכנים

סוכן התכנות יכול להקצות משימות מחקר או משימות בארגז חול (sandbox) עם כמה שלבים לסוכנים מנוהלים של 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. כדי להגדיר ארגזי חול של נציגים, עיינו בקטע סביבות.

גופי בקשות בהתאמה אישית

לאפשרויות בלי דגלים ייעודיים, מעבירים מטען ייעודי (payload) גולמי של Interactions API בפורמט JSON עם --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 מוטבע מוגבל ל-14MB של נתוני קובץ גולמיים (מטען ייעודי (payload) של בקשה בגודל 20MB, כולל קידוד base64). אפשר להעלות קבצים גדולים באמצעות gemini-api files upload. ‫Files API מוחק קבצים שהועלו אחרי 48 שעות.
• ‫gemini-api תומך בבקשות HTTP רגילות, בסטרימינג של SSE ובסקרים אסינכרוניים, ולא ב-WebSockets דו-כיווניים. כדי להעביר סטרימינג של קול ווידאו בזמן אמת, השתמשו ב-Live API עם Google GenAI SDK.

המאמרים הבאים

• הגדרת סוכן התכנות
• Interactions API
• סוכנים מנוהלים ב-Gemini
• ‫gemini-api-cli ב-GitHub