آموزش Google Antigravity CLI: راهنمای کامل ایجنت گوگل

Google Antigravity CLI رابط ترمینالی پلتفرم ایجنت Antigravity گوگل است. این ابزار می‌تواند مخزن را بررسی کند، برای کار چندمرحله‌ای استدلال کند، چند فایل را تغییر دهد، ابزار اجرا کند، برنامه و diff را به‌شکل artifact قابل بازبینی نشان دهد، ساب‌ایجنت بسازد و تاریخچه گفتگو را نگه دارد. CLI هسته ایجنت و بخشی از تنظیمات Antigravity 2.0 را به اشتراک می‌گذارد، اما برای shell محلی، SSH، tmux، اتوماسیون و سربار کم طراحی شده است.

این آموزش در ۱۵ مرداد ۱۴۰۵ (۶ اوت ۲۰۲۶) با مستندات رسمی Antigravity CLI، مقاله معرفی و changelog زنده تطبیق داده شد. هنگام بازبینی، مستندات CLI را نسخه 1.1.10 و Antigravity 2.0 را نسخه 2.5.0 معرفی می‌کردند. انتشار ممکن است تدریجی باشد؛ پیش از اتکا به قابلیت جدید، agy --version و changelog را ببینید.

تصویر رسمی مقاله معرفی Antigravity CLI گوگل.

تفاوت CLI، نسخه 2.0، IDE و SDK

Antigravity یک خانواده محصول است و هر سطح نقش متفاوتی دارد:

• Antigravity CLI رابط ترمینالی صفحه‌کلیدمحور برای کار محلی، SSH و اجرای headless است؛
• Antigravity 2.0 محیط تصویری دسکتاپ برای پروژه، گفتگو، artifact، فایل و ارکستریشن وسیع‌تر است؛
• Antigravity IDE تجربه ایجنت را به گردش‌کار ویرایشگرهای پشتیبانی‌شده می‌آورد؛
• Antigravity SDK پلتفرم را برای اپلیکیشن و اتوماسیون سفارشی در دسترس می‌گذارد.

طبق مقایسه رسمی، CLI و Antigravity 2.0 هسته ایجنت مشترک دارند، تنظیمات اصلی و امنیتی را همگام می‌کنند و می‌توان گفتگو را از ترمینال به محیط تصویری منتقل کرد. با این حال سطح‌ها یکسان نیستند؛ ناوبری صفحه‌کلید، rendering ترمینال، خروجی headless و پنل‌های دسکتاپ ویژگی‌های همان سطح‌اند.

اگر مخزن و shell مرکز کار است، CLI مناسب‌تر است. وقتی کار به مدیریت بصری پروژه یا مرور گسترده artifact نیاز دارد به نسخه 2.0 بروید. SDK را زمانی انتخاب کنید که یک integration تکرارپذیر ارزش نگه‌داری کد اضافه را دارد.

نصب و احراز هویت امن

راهنمای شروع رسمی این مسیرها را ارائه می‌کند.

macOS یا Linux:

curl -fsSL https://antigravity.google/cli/install.sh | bash

Windows PowerShell:

irm https://antigravity.google/cli/install.ps1 | iex

مسیر پیش‌فرض باینری در macOS/Linux برابر ~/.local/bin/agy و در Windows زیر پوشه local application data کاربر است. روی ماشین حساس یا سازمانی، اسکریپت دوردست را پیش از اجرا بررسی کنید. سپس نسخه واقعی را ببینید:

agy --version
agy --help

با اجرای agy ورود Google در مرورگر را کامل کنید. راهنمای نصب و احراز هویت ذخیره امن در OS keyring، ورود SSH با URL و کد، تنظیمات سازمانی، proxy و /logout را پوشش می‌دهد. نسخه 1.1.10 همچنین مسیر Gemini Enterprise، Workforce Identity Federation و Application Default Credentials را دارد. هویتی را انتخاب کنید که واقعاً برای مخزن و Cloud project مجاز است؛ token را در prompt یا فایل مخزن نگذارید.

فقط به workspace دقیق اعتماد کنید

از همان پروژه‌ای شروع کنید که باید در اختیار ایجنت قرار گیرد:

cd /path/to/project
git status --short --branch
agy

اجرای اول درباره رنگ، حالت rendering و Workspace Trust می‌پرسد. اعتماد مهم است: پس از تأیید، ایجنت فایل‌ها را index می‌کند و می‌تواند ابزار درخواست کند. اگر کار فقط یک package را نیاز دارد، از home directory یا ریشه بسیار بزرگ monorepo اجرا نکنید. برای ویرایش از branch تمیز یا worktree موقت استفاده کنید.

نخست درخواست فقط‌خواندنی بدهید:

مسیر احراز هویت را از ورودی درخواست تا persistence توضیح بده.
فایل‌ها و مرزهای اعتماد را نام ببر؛ هنوز ویرایش یا فرمان اجرا نکن.

سپس قرارداد محدود اجرای کار را مشخص کنید:

با یک تست هدفمند باگ ارسال تکراری را بازتولید کن. کوچک‌ترین اصلاح را پیشنهاد بده،
برنامه را برای بازبینی نشان بده، فقط فایل‌های تأییدشده را تغییر بده، تست هدفمند و
type check را اجرا و diff نهایی را خلاصه کن. commit، push یا deploy نکن.

این کار وضعیت مخزن، شواهد و مرز تأیید را روشن می‌کند و آن‌ها را به حدس مدل نمی‌سپارد.

اسکرین‌شات رسمی محصول؛ شخصی‌سازی اجرای اول و diff قابل بازبینی را کنار هم نشان می‌دهد.

کار با plan، artifact، diff و تست

Antigravity خروجی‌های مهم را به‌شکل artifact ارائه می‌کند. plan، ویرایش فایل، diff، اجرای تست یا سند تولیدی باید به‌عنوان مدرک بررسی شود؛ پیام «انجام شد» در چت کافی نیست. راهنمای artifact viewer و گردش‌کار بازبینی را توضیح می‌دهد و /diff نمای متمرکز تغییرهای workspace است.

یک حلقه مطمئن چنین است:

1. ابتدا بررسی مخزن و plan را بخواهید؛
2. مطمئن شوید plan فایل و تست پذیرش درست را نام می‌برد؛
3. فقط ابزار یا ویرایش ضروری بعدی را تأیید کنید؛
4. کل diff را ببینید، نه فقط خلاصه ایجنت؛
5. تست هدفمند و سپس gate گسترده مرتبط را اجرا کنید؛
6. سناریوی اصلی را دوباره بازتولید کنید؛
7. با git status فایل ناخواسته یا تولیدی را پیدا کنید.

سیاست artifact قابل تنظیم است. برای مخزن ناآشنا، درخواست بازبینی پیش‌فرض منطقی است. گزینه «agent decides» کنترل امنیتی مستقل نیست و «always proceed» برای مخزنی با credential، دسترسی تولید یا کار جایگزین‌ناپذیر مناسب نیست.

انتخاب مدل و reasoning effort

با /model مدل‌های واقعاً در دسترس حساب و با /effort سطح استدلال پشتیبانی‌شده را ببینید. نسخه‌های فعلی stable model slug و flagهای --model و --effort دارند:

agy --model="<model-slug>" --effort=high

نام مدل را از اسکرین‌شات قدیمی کپی نکنید. entitlement، منطقه، quota و سطح effort ممکن است تغییر کند. نسخه 1.1.10 باگی را رفع کرده که گاهی flag مدل یا effort را نادیده می‌گرفت؛ بنابراین پیش از آزمایش تکرارپذیر به‌روزرسانی کنید.

برای جست‌وجوی مخزن، formatting و نگه‌داری قطعی از effort پایین‌تر استفاده کنید. برای معماری، debug ظریف، migration یا review بزرگ effort بالاتر را بیازمایید و کیفیت پذیرفته‌شده، زمان و credit را مقایسه کنید. بهترین تنظیم، ارزان‌ترین گزینه‌ای است که تست پذیرش واقعی شما را پایدار پاس می‌کند.

واگذاری کار به ساب‌ایجنت‌ها

پنل /agents ایجنت داخلی و سفارشی را نشان می‌دهد و runtime می‌تواند ساب‌ایجنت تخصصی تعریف و اجرا کند. نسخه‌های فعلی کار child را نمایش می‌دهند، ساب‌ایجنت بازگشتی دارند و اجازه می‌دهند custom agent سطح مدل خود را مشخص کند. مستندات subagent ساخت و کنترل آن را توضیح می‌دهد.

اسکرین‌شات رسمی گوگل از ساب‌ایجنت‌های UI، داده و کیفیت کد برای یک مأموریت.

واگذاری خوب، شواهد مستقل را جدا می‌کند:

• یک ایجنت مسیر کد را نقشه‌برداری کند؛
• یک ایجنت تست‌ها را بخواند و مشکل را بازتولید کند؛
• یک ایجنت review فقط‌خواندنی امنیت یا رگرسیون انجام دهد؛
• coordinator یک نتیجه را ادغام و اعتبارسنجی نهایی را اجرا کند.

دو ایجنت را برای ویرایش هم‌زمان یک فایل در یک worktree نفرستید. برای پیاده‌سازی موازی worktree جدا بسازید و مالکیت فایل، خروجی مورد انتظار و ترتیب ادغام را روشن کنید. ساب‌ایجنت اختیار معناداری از parent می‌گیرد؛ مدل، ارث‌بری MCP و سیاست اجرای فرمانش را پیش از اجرای بدون نظارت بررسی کنید.

اتوماسیون با print mode و خروجی ساختاریافته

برای script و CI از print mode استفاده کنید، نه استخراج متن از رابط ترمینال:

agy -p "این diff را از نظر درستی مرور و یافته‌های کوتاه برگردان"

نسخه‌های فعلی خروجی text، json و stream-json و همچنین JSON Schema سفارشی دارند. الگوی کلی:

agy -p "این تغییر را طبقه‌بندی کن" \
  --output-format json \
  --json-schema ./schemas/review-result.json

stream رویدادهای typed برای پیشرفت و نتیجه نهایی و metadata ابزار و ساب‌ایجنت می‌فرستد. این قابلیت برای CI، ارزیابی و dashboard مفید است، اما خروجی ساختاریافته ایجنت را deterministic نمی‌کند. schema، exit code، فایل‌های تغییرکرده و شواهد تست را اعتبارسنجی کنید. اجرای headless نمی‌تواند تأیید تعاملی بگیرد؛ سیاست فعلی ابزار نیازمند تأیید را soft-deny می‌کند. به‌جای ضعیف‌کردن کل profile، مجوز non-interactive صریح تعریف کنید.

افزودن rule، Skill، پلاگین، hook و MCP

Antigravity از rule مخزن، Agent Skill، پلاگین، hook و MCP پشتیبانی می‌کند و هرکدام مسئله متفاوتی را حل می‌کند:

• rule قرارداد و مرز پایدار مخزن است؛
• Skill روند تکرارپذیر و منابع پشتیبان را بسته‌بندی می‌کند؛
• plugin مجموعه سازگار customization است؛
• hook بررسی deterministic را در رویداد lifecycle اجرا می‌کند؛
• MCP ابزار یا داده بیرونی را با پروتکل استاندارد متصل می‌کند.

راهنمای plugins و skills discovery و مدیریت را پوشش می‌دهد. rule را کوتاه، command را واقعی و trigger مهارت را محدود بنویسید. برای format، test یا policy قطعی از hook استفاده کنید. هر بار فقط یک MCP بیفزایید، ابزارهای لازم را allowlist کنید، scope احراز هویت و مقصد داده را ببینید و timeout قرار دهید. صفحه وب یا ticket می‌تواند prompt injection داشته باشد، حتی اگر ارائه‌دهنده MCP معتبر باشد.

نسخه‌های تازه hook مشترک را زیر ~/.gemini/config/ همگام می‌کنند، agent سفارشی Markdown دارند، Skill را در headless گسترش می‌دهند، MCP را بدون مسدودکردن شروع interactive بار می‌کنند و باگ پلاگین غیرفعالی را رفع کرده‌اند که hook آن همچنان اجرا می‌شد. پس ابزار را به‌روز نگه دارید و مطمئن شوید «disabled» واقعاً به معنی توقف اجراست.

تنظیم مجوز و sandbox

/config یا /settings را باز و محافظه‌کارانه شروع کنید. مرجع تنظیمات چهار حالت مجوز دارد:

• request-review پیش از write، shell یا web اجازه می‌خواهد و پیش‌فرض است؛
• proceed-in-sandbox فرمان sandboxشده را خودکار و بقیه را با بازبینی اجرا می‌کند؛
• strict برای هر ابزار غیرخواندنی می‌پرسد؛
• always-proceed prompt را حذف می‌کند و پرریسک‌ترین حالت است.

بازبینی artifact را روشن نگه دارید، sandbox ترمینال را فعال کنید و non-workspace access را تا وقتی نیاز واقعی ندارید خاموش بگذارید. نسخه 1.1.10 دسترسی .git را در sandbox فقط‌خواندنی کرد تا metadata دیده شود ولی بازنویسی نشود. sandbox دسترسی host را کم می‌کند، اما محتوای شبکه را قابل اعتماد نمی‌کند و جلوی سوءاستفاده از credentialی که خودتان mount کرده‌اید را نمی‌گیرد.

اسکرین‌شات رسمی مستندات است؛ مقادیر نمایش‌داده‌شده نمونه‌اند و باید با ریسک شما تنظیم شوند.

تنظیمات پایدار CLI در این مسیر است:

~/.gemini/antigravity-cli/settings.json

keybinding سفارشی در keybindings.json کنار آن قرار می‌گیرد. فقط مقدار متفاوت با پیش‌فرض روی دیسک نوشته می‌شود. برای اعتبارسنجی schema از editor داخلی استفاده و secret را از هر دو فایل دور نگه دارید.

جابه‌جایی میان CLI و Antigravity 2.0

CLI و نسخه 2.0 برای همکاری طراحی شده‌اند. وقتی تحقیق ترمینالی به مدیریت بصری پروژه تبدیل شد، از مسیر رسمی export/import گفتگو استفاده کنید. چون تنظیمات مشترک‌اند، تغییر مجوز می‌تواند بر هر دو سطح اثر بگذارد؛ پس پس از انتقال policy همگام‌شده را ببینید.

کاربران Gemini CLI می‌توانند از گردش‌کار migration برای واردکردن یک‌باره extension، Skill و تنظیم سازگار استفاده کنند. customization واردشده را مثل کد ببینید: server قدیمی را حذف، credential کهنه را rotate، hook را بررسی و رفتار مجوز را ابتدا در پروژه موقت آزمایش کنید.

گردش‌کار حرفه‌ای Antigravity

1. Scope: کوچک‌ترین workspace معتبر و وضعیت branch را ثبت کنید؛
2. Inspect: معماری و شواهد را بدون ویرایش بخواهید؛
3. Plan: فایل، تست، عمل ممنوع و نقطه تأیید را توافق کنید؛
4. Isolate: برای mutation یک branch یا worktree بسازید؛
5. Implement: اقدام محدود را تأیید و انحراف را فوری اصلاح کنید؛
6. Verify: تست هدفمند، gate گسترده مرتبط و QA runtime/browser را اجرا کنید؛
7. Review: artifact، کل diff و فایل ناخواسته را بررسی کنید؛
8. Cross-check: بازبین یا ساب‌ایجنت مستقل فقط‌خواندنی به کار بگیرید؛
9. Handoff: فرمان، نتیجه، ریسک باقی‌مانده و عمل بیرونی انجام‌نشده را گزارش کنید.

برای مقایسه مدل، یک task ثابت مخزن و تست پذیرش یکسان به کار ببرید. نسخه، model slug، effort، مجوز، prompt، زمان، credit، نتیجه پذیرفته‌شده و اصلاح انسانی را ثبت کنید. نمودار benchmark فروشنده برای کشف گزینه مفید است، اما جای workload شما را نمی‌گیرد.

رفع اشکال

agy پیدا نمی‌شود: shell تازه باز کنید، حضور ~/.local/bin در PATH را ببینید و مراحل دستی راهنمای نصب را اجرا کنید.

ورود مرورگر روی SSH کار نمی‌کند: از URL و کد نمایش‌داده‌شده، راهنمای keyring/D-Bus یا مسیر سازمانی/ADC استفاده کنید. کد را در issue یا log مشترک نگذارید.

model یا effort نادیده گرفته می‌شود: به 1.1.10 یا جدیدتر ارتقا دهید، /model و /effort را اجرا و status line واقعی را بررسی کنید.

فرمان پیوسته مسدود می‌شود: /permissions، اولویت rule پروژه و global، non-workspace، شبکه و log sandbox را بررسی کنید. برای حذف یک prompt مبهم، کل محیط را روی always-proceed نگذارید.

MCP در startup گیر می‌کند: CLI را به‌روز، server مشکوک را خاموش، OAuth و transport را بررسی، timeout تعریف و serverها را تک‌تک فعال کنید.

دو session یک گفتگو را تغییر می‌دهند: گفتگو را fork یا یکی را ببندید. نسخه جدید هشدار می‌دهد چون trajectory و ویرایش درهم‌تنیده قابل اتکا نیست.

پرسش‌های رایج

آیا Antigravity CLI همان Gemini CLI است؟

خیر. Antigravity CLI هسته مشترک Antigravity، artifact، تنظیمات، ساب‌ایجنت و اتصال به Antigravity 2.0 را دارد. برای تنظیم و extension سازگار Gemini CLI مسیر migration یک‌باره ارائه شده است.

آیا در CI قابل استفاده است؟

بله، با print mode و خروجی ساختاریافته. runner ایزوله، مجوز صریح، credential فقط‌خواندنی، اعتبارسنجی schema، کنترل diff و بازبینی انسانی پیش از merge یا deploy لازم است.

Antigravity، Codex، Claude Code یا OpenCode؟

Antigravity برای پلتفرم مشترک CLI و محیط تصویری گوگل است؛ Codex برای اکوسیستم local، cloud، app و API اوپن‌ای‌آی؛ Claude Code برای ترمینال، وب، دسکتاپ، Agent SDK و agent team آنتروپیک؛ و OpenCode برای پوسته متن‌باز و چندارائه‌دهنده. همه را با task یکسان مخزن بسنجید.

آیا Workspace Trust هر فرمانی را امن می‌کند؟

خیر. trust امکان index و درخواست ابزار می‌دهد. مجوز، artifact review، sandbox، محدودیت بیرون workspace، scope credential و بازبینی انسانی کنترل‌های جدا هستند.

یادداشت منابع

بازبینی‌شده در ۱۵ مرداد ۱۴۰۵ / ۶ اوت ۲۰۲۶:

• مرور Antigravity CLI
• راهنمای شروع
• نصب و احراز هویت
• تنظیمات، rendering و keybinding
• مجوز و sandbox
• ساب‌ایجنت‌ها
• پلاگین و Skill
• حالت headless
• changelog رسمی
• مقاله رسمی معرفی