۱. مقدمه
در این آزمایشگاه کد، شما با رابط خط فرمان Gemini ، یک عامل هوش مصنوعی متنباز که قدرت Gemini را مستقیماً به ترمینال شما میآورد، آشنا خواهید شد.
آنچه یاد خواهید گرفت
- نصب و پیکربندی رابط خط فرمان Gemini
- بررسی ابزارها، دستورات داخلی و پیکربندی سرورهای MCP در Gemini CLI
- سفارشیسازی رابط خط فرمان Gemini از طریق فایل
GEMINI.md - بررسی چند مورد استفاده با Gemini CLI
آنچه نیاز دارید
این codelab را میتوان بهطور کامل در Google Cloud Shell اجرا کرد، که از قبل با Gemini CLI نصب شده است.
از طرف دیگر، اگر ترجیح میدهید روی دستگاه خودتان کار کنید، بخشی برای نصب Gemini CLI به صورت محلی وجود دارد.
شما به موارد زیر نیاز خواهید داشت:
- مرورگر وب کروم
- یک حساب جیمیل
این آزمایشگاه کد، برای کاربران و توسعهدهندگان در تمام سطوح (از جمله مبتدیان) طراحی شده است. موارد استفاده در آزمایشگاه کد به وظایف توسعهدهنده و غیر توسعهدهنده طبقهبندی شدهاند. موارد استفاده توسعهدهنده، نحوه کدنویسی با Gemini CLI و کار با مخزن GitHub را برای انجام وظایف توسعه رایج مانند توضیح/درک کد، تولید مستندات، رفع مشکلات و موارد دیگر نشان میدهد. توصیه میشود این موارد استفاده را در آزمایشگاه کد تکمیل کنید. در انتها یک بخش اختیاری وجود دارد که چندین کار روزمره را که متمرکز بر غیر توسعهدهنده هستند، پوشش میدهد.
۲. قبل از شروع
ایجاد یک پروژه
- در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
- شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا میشود و bq از قبل روی آن بارگذاری شده است، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
- پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی میکنید که آیا از قبل احراز هویت شدهاید و پروژه روی شناسه پروژه شما تنظیم شده است یا خیر:
gcloud auth list
- دستور زیر را در Cloud Shell اجرا کنید تا تأیید شود که دستور gcloud از پروژه شما اطلاع دارد.
gcloud config list project
- اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:
gcloud config set project <YOUR_PROJECT_ID>
۳. نصب
قبل از انجام تنظیمات و اجرای Gemini CLI، بیایید یک پوشه ایجاد کنیم که از آن به عنوان پوشه اصلی برای تمام پروژههایی که درون آن ایجاد میکنیم استفاده خواهیم کرد. این یک نقطه شروع برای کار Gemini CLI است، اگرچه به برخی پوشههای دیگر روی سیستم شما نیز اشاره خواهد کرد که در صورت نیاز بعداً به آنها مراجعه خواهید کرد.
یک پوشه نمونه ( gemini-cli-projects ) ایجاد کنید و از طریق دستورات نشان داده شده در زیر به آن بروید. اگر ترجیح میدهید از نام پوشه دیگری استفاده کنید، لطفاً این کار را انجام دهید.
mkdir gemini-cli-projects
بیایید به آن پوشه برویم:
cd gemini-cli-projects
شما میتوانید مستقیماً از طریق دستور gemini ، رابط خط فرمان Gemini را اجرا کنید.
لطفاً مستقیماً به بخش بعدی (پیکربندی رابط خط فرمان Gemini از طریق settings.json) بروید.
اگر میخواهید Gemini CLI را به صورت محلی نصب کنید، دستورالعملهای زیر را دنبال کنید. توجه داشته باشید که Gemini CLI از قبل روی Cloud Shell و Cloud Workstations نصب شده است.
اولین قدم نصب Node 20+ روی دستگاه شماست. پس از اتمام این کار، میتوانید Gemini CLI را از طریق هر یک از روشهای زیر نصب و اجرا کنید:
- شما میتوانید ابتدا Gemini CLI را به صورت سراسری روی سیستم خود نصب کنید. برای انجام این مرحله ممکن است به دسترسی ادمین نیاز داشته باشید.
# option 1: install Gemini CLI
npm install -g @google/gemini-cli
# .. and then run
gemini
- با دستور زیر آن را اجرا کنید:
# option 2: run without installing Gemini CLI
npx https://github.com/google-gemini/gemini-cli
میتوانید با اجرای دستور زیر از نصب CLI اطمینان حاصل کنید:
gemini --version
با فرض اینکه Gemini CLI را از طریق هر یک از روشهای بالا اجرا کردهاید، در اولین اجرا، ممکن است از شما در مورد انتخاب تم سوال شود. در این صورت، میتوانید از تم پیشفرض استفاده کنید یا تم دلخواه خود را انتخاب کنید.
نکته مهم بعدی احراز هویت است. در این مرحله از شما روش احراز هویت پرسیده میشود. توصیه میشود در این آزمایش از حساب گوگل شخصی خود استفاده کنید و از حسابهای غیر گوگل یا حسابهای مرتبط با Google Workspace استفاده نکنید.
اگر با سهمیه رایگان فعلی که به حسابهای گوگل داده میشود، به محدودیت برخوردید، میتوانید از کلید API Gemini یا حتی Google Cloud Vertex AI استفاده کنید، که در آن به یک شناسه پروژه و نام مکان برای آن پروژه نیاز خواهید داشت. اگر قصد دارید از روشهای دیگر احراز هویت استفاده کنید، به بخش احراز هویت در مستندات مراجعه کنید.
ادامه دهید و روی Enter کلیک کنید. این کار یک صفحه احراز هویت گوگل در مرورگر باز میکند. احراز هویت را با حساب گوگل خود انجام دهید، شرایط را بپذیرید و پس از تأیید موفقیتآمیز، متوجه خواهید شد که رابط خط فرمان Gemini آماده و منتظر دستور شماست.
نمونهای از اسکرینشات در زیر آورده شده است:
در این مورد، ما گزینه Vertex AI را انتخاب کردهایم، اما در مورد شما میتواند حساب شخصی باشد. متوجه خواهید شد که ما مدل Gemini 2.5 (که در پایین سمت راست قابل مشاهده است) را انتخاب کردهایم. شما میتوانید مدل خاص خود را در هر زمان با استفاده از دستور /model انتخاب کنید.
۴. پیکربندی رابط خط فرمان Gemini از طریق settings.json
اگر Cloud Shell را برای اجرای Gemini انتخاب کنید، یک تم پیشفرض برای Gemini CLI و روش احراز هویت از قبل برای شما انتخاب و پیکربندی شده است.
اگر Gemini CLI را روی دستگاه خود نصب کرده و برای اولین بار آن را اجرا کردهاید، یک تم و سپس یک روش احراز هویت را انتخاب کردهاید.
اکنون، در اجراهای بعدی Gemini CLI، دیگر از شما خواسته نمیشود که یک قالب و روش احراز هویت را انتخاب کنید. این بدان معناست که در جایی ذخیره میشود و فایلی که از آن استفاده میکند settings.json نام دارد و این روشی برای سفارشیسازی Gemini CLI است.
تنظیمات با اولویت زیر اعمال میشوند (Cloud Shell فقط تنظیمات کاربر را در دسترس قرار میدهد):
- سیستم:
/etc/gemini-cli/settings.json(برای همه کاربران اعمال میشود، تنظیمات کاربر و فضای کاری را لغو میکند). - فضای کاری:
.gemini/settings.json(تنظیمات کاربر را لغو میکند). - کاربر:
~/.gemini/settings.json.
کاربر ویندوز : %USERPROFILE%.gemini\settings.json (که معمولاً به C:\Users<YourUsername>.gemini\settings.json گسترش مییابد)
System : %ProgramData%\gemini-cli\settings.json (که معمولاً به C:\ProgramData\gemini-cli\settings.json گسترش مییابد)
کاربر مک : ~/.gemini/settings.json (که به /Users/<YourUsername>/.gemini/settings.json گسترش مییابد)
سیستم : /etc/gemini-cli/settings.json
اگر به خاطر داشته باشید، در زمان انتخاب قالب، تنظیمات را طوری انتخاب کردید که در تنظیمات کاربر ذخیره شوند. بنابراین به ~/.gemini folder بروید و فایل settings.json را مشاهده خواهید کرد.
فایل settings.json من در زیر نشان داده شده است. اگر قالب دیگری را انتخاب کرده بودید، نام آن را در آنجا مشاهده میکردید.
{
"security": {
"auth": {
"selectedType": "oauth-personal" or "cloud-shell"
}
},
"ui": {
"theme": "Default"
}
}
۵. اولین تعامل ما با رابط خط فرمان Gemini
بیایید با Gemini CLI شروع کنیم و اولین کوئری خود را مطابق شکل زیر تایپ کنیم:
Give me a famous quote on Artificial Intelligence and who said that?
پاسخ مورد انتظار در زیر نشان داده شده است:
> Give me a famous quote on Artificial Intelligence and who said that?
✦ "The only way to do great work is to love what you do." - Steve Jobs (While not directly about AI, it's a famous quote related to technology and innovation, which underpins AI development.)
Alternatively:
"The development of full artificial intelligence could spell the end of the human race." - Stephen Hawking
یک راه سریع برای درک رابط خط فرمان Gemini و دستورات مختلفی که پشتیبانی میکند، تایپ کردن /help (علامت اسلش رو به جلو) است و انواع دستورات و میانبرهای صفحه کلید را مشاهده خواهید کرد.
بیایید فعلاً از Gemini CLI خارج شویم. میتوانید این کار را یا از طریق دستور /quit انجام دهید یا میتوانید دو بار Ctrl-C در جلسه ترمینال تعاملی Gemini CLI فشار دهید. وقتی از Gemini CLI خارج میشوید، آمار جلسه شما را نشان میدهد که بینشی در مورد جلسه، میزان استفاده از مدل و سایر معیارها به شما میدهد.
۶. رابط خط فرمان Gemini - پارامترهای فرمان
چند پارامتر خط فرمان وجود دارد که میتوان هنگام شروع Gemini CLI ارائه داد. برای دریافت لیست کامل گزینهها، میتوانید از --help همانطور که در زیر نشان داده شده است استفاده کنید.
gemini --help
این باید طیف کامل گزینههای موجود را نشان دهد. توصیه میشود مستندات اینجا را مطالعه کنید.
بیایید نگاهی به چند مورد از آنها بیندازیم. اولین مورد، پیکربندی Gemini CLI برای استفاده از یک حالت خاص Gemini است. در حال حاضر، در زمان بهروزرسانی این آزمایشگاه، لیست مدلهای پشتیبانیشده در اینجا آمده است. برای استفاده از یک مدل خاص، میتوانید این کار را در زمان شروع Gemini CLI از طریق پارامتر -m همانطور که در زیر نشان داده شده است، انجام دهید:
gemini -m "gemini-2.5-flash"
متوجه خواهید شد که اگر به روش بالا شروع کنید، میتوانید مدل را در پایین سمت راست ترمینال Gemini CLI بررسی کنید.
وقتی در برنامه Gemini CLI هستید، میتوانید از دستور /model برای باز کردن پنجرهای استفاده کنید که به شما امکان انتخاب مدل را میدهد. یک نمونه اجرا در زیر نشان داده شده است و بسته به نیازها و راهنماییهای ارائه شده، میتوانید مدل را تغییر دهید تا بسته به پیچیدگی و نیاز به کنترل هزینهها، مدل مناسب را برای کار انتخاب کنید.
حالت غیر تعاملی
یک گزینه جالب، اجرای Gemini CLI در حالت غیر تعاملی است. این بدان معناست که شما مستقیماً اعلان را به آن ارائه میدهید و بدون باز شدن ترمینال تعاملی Gemini CLI، به آن پاسخ میدهد. اگر قصد دارید از Gemini CLI به صورت خودکار به عنوان بخشی از اسکریپت یا هر فرآیند اتوماسیون دیگری استفاده کنید، این گزینه بسیار مفید است. شما از پارامتر -p برای ارائه اعلان به Gemini CLI مانند تصویر زیر استفاده میکنید:
gemini -p "What is the gcloud command to deploy to Cloud Run"
به خاطر داشته باشید که امکانی برای ادامه مکالمه با سوالات تکمیلی وجود ندارد. این حالت همچنین به شما اجازه نمیدهد ابزارها (از جمله WriteFile) را مجاز کنید یا دستورات shell را اجرا کنید.
به یاد داشته باشید که اگر پارامتر -p را از قلم بیندازید و فقط کد زیر را وارد کنید، خط فرمان Gemini با اعلان مربوطه باز میشود و ادامه کار در داخل آن انجام میشود.
gemini "What is the gcloud command to deploy to Cloud Run"
۷. رابط خط فرمان Gemini - ابزارهای داخلی
رابط خط فرمان Gemini با مجموعهای از ابزارهای داخلی ارائه میشود و در مستندات ابزارها آمده است: «مدل Gemini از این ابزارها برای تعامل با محیط محلی شما، دسترسی به اطلاعات و انجام اقدامات استفاده میکند. این ابزارها قابلیتهای رابط خط فرمان را افزایش میدهند و آن را قادر میسازند تا فراتر از تولید متن عمل کند و به طیف گستردهای از وظایف کمک کند.»
برای دریافت لیستی از ابزارهای داخلی فعلی، دستور /tools را مطابق شکل زیر فراخوانی کنید:
Available Gemini CLI tools:
- Activate Skill (activate_skill)
- Ask User (ask_user)
- Edit (replace)
- Enter Plan Mode (enter_plan_mode)
- FindFiles (glob)
- GoogleSearch (google_web_search)
- Invoke Subagent (invoke_agent)
- List Background Processes (list_background_processes)
- Read Background Output (read_background_output)
- ReadFile (read_file)
- ReadFolder (list_directory)
- SearchText (grep_search)
- Shell (run_shell_command)
- Update Topic Context (update_topic)
- WebFetch (web_fetch)
- WriteFile (write_file)
یکی از چیزهایی که باید فوراً به ذهنتان خطور کند این است که از خود بپرسید آیا رابط خط فرمان Gemini میتواند به سادگی این ابزارها را در هر زمان که بخواهد فراخوانی کند؟ پاسخ پیشفرض خیر است، وقتی صحبت از عملیات حساسی میشود که ممکن است شامل نوشتن در سیستم محلی، خواندن از یک سیستم خارجی، رفتن به شبکه خارجی و غیره باشد.
اگرچه هنگام شروع CLI یک --yolo در دسترس است (که معمولاً توصیه نمیشود)، متوجه خواهید شد که Gemini CLI از شما اجازه اجرای ابزاری را که انتخاب کرده است، میخواهد. میتوانید این اجازه را رد کنید، یا اجازه دهید یک بار اجرا شود یا به آن اجازه کلی برای همیشه اجرا شدن بدهید. شما کنترل کامل امور را در دست دارید و باید داشته باشید.
بیایید از یک اعلان استفاده کنیم که باعث میشود Gemini CLI یکی از ابزارهای داخلی را برای اجرا انتخاب کند و این به شما درک خوبی از نحوه عملکرد آن میدهد.
سناریویی را تصور کنید که میخواهید در مورد آخرین اخبار مالی در سراسر جهان اطلاعات کسب کنید و آن را در فایلی در دایرکتوری کاری محلی که Gemini CLI را از آنجا راهاندازی کردهاید، ذخیره کنید. از دستور زیر استفاده کنید:
Search for the latest headlines today in the world of finance and save them in a file named finance-news-today.txt
برای لحظهای تصور کنید که چه کاری باید انجام دهد. در حالت ایدهآل، باید برای دریافت اخبار از منابع اطلاعاتی مرتبط که میتوانند اخبار مالی را در اختیارش قرار دهند، در گوگل جستجو کند. سپس باید فایلی با نام finance-news-today.txt (یک عملیات نوشتن روی سیستم محلی شما که به اجازه شما نیاز دارد) با محتوای آن ایجاد کند.
بیایید ببینیم چه اتفاقی میافتد (شما باید همین کار را روی دستگاه خود انجام دهید).
اولین کاری که انجام میدهد این است که ابزار GoogleSearch را برای جستجو در وب و بازیابی نتایج فراخوانی میکند، همانطور که در زیر نشان داده شده است:
Searching for Finance News:
I will first search for the latest finance headlines and then save them to a file.
✓ GoogleSearch Searching the web for: "latest finance headlines"
→ Search results for "latest finance headlines" returned.
Saving Finance News: I will now save the finance headlines to the file 'finance-news-today.txt'.
پس از انجام این کار، آماده نوشتن این فایل است و از ابزار WriteFile استفاده میکند، اما از آنجایی که این یک عملیات حساس ( نوشتن ) است، از شما اجازه میخواهد. میتوانید نوع مجوز را تعیین کنید، مثلاً اجازه یک بار، اجازه همیشه و غیره. فعلاً اجازه یک بار را انتخاب کنید.
سپس اطلاعات در فایل نوشته میشود و پیام موفقیتآمیز در زیر نشان داده میشود:
✦ I have saved the latest finance news to finance-news-today.txt.
Finance News Saved: The task is complete.
چگونه بررسی میکنید که آیا فایل نوشته شده است یا خیر؟ میتوانید از @file برای درخواست خواندن محتوا استفاده کنید. وقتی @ را تایپ میکنید، لیستی از فایلهای موجود در پوشه فعلی نمایش داده میشود و فایلی که اخیراً ایجاد شده است را نشان میدهد. آن را انتخاب کنید و اعلان را ارسال کنید. اعلان من در زیر نشان داده شده است:
read the contents of @finance-news-today.txt
این منجر به فراخوانی ابزارهای مورد نیاز (ReadManyFiles، ReadFile) میشود و محتویات آن مطابق شکل زیر نمایش داده میشود:
✓ ReadManyFiles Attempting to read files from finance-news-today.txt → Read 1 file(s)
Topic: Summarizing the financial news headlines.
✦ The latest finance headlines as of May 15, 2026, include:
Global Markets & Economy:
* The Dow Jones Industrial Average