headless VPS پر Gemini CLI کیسے چلائیں

آپ کیا بنا رہے ہیں

آپ کے اپنے سرور پر ایک ہمیشہ فعال Gemini CLI، جو SSH کے ذریعے قابل رسائی ہے۔ یہ طویل ایجنٹ کام چلاتا ہے جو لیپ ٹاپ بند کرنے کے بعد بھی جاری رہتے ہیں۔ تنصیب صرف تین کمانڈز پر مشتمل ہے۔ زیادہ مشکل وہ سب کچھ ہے جو ڈیسک ٹاپ کا فرض کرتا ہے۔ Google کا CLI لاگ ان کے لیے براؤزر کھولنا چاہتا ہے، اور آپ کے سرور پر براؤزر موجود نہیں ہے۔ اس لیے اس گائیڈ کا زیادہ تر حصہ ہیڈلیس طریقہ کار پر ہے۔ اس میں شامل ہے: ایک موجودہ Node جو ڈسٹرو فراہم نہیں کرے گا، ایک گلوبل npm تنصیب جس کے لیے root کی ضرورت نہیں، API کلید کے ساتھ بغیر براؤزر کی توثیق جسے آپ اپنی شیل ہسٹری سے باہر رکھتے ہیں، اور tmux تاکہ منقطع ہونے والا SSH سیشن چلتے ہوئے کام کو ختم نہ کرے۔

Gemini CLI ایک اوپن سورس (Apache-2.0) Node پروگرام ہے (@google/gemini-cli) جو Google کے Gemini ماڈلز سے بات کرتا ہے اور فائلیں پڑھ اور لکھ سکتا ہے، شیل کمانڈز چلا سکتا ہے، اور ورکنگ ڈائریکٹری میں ٹولز کو چلا سکتا ہے۔ VPS پر یہ ایک چھوٹا، ہمیشہ دستیاب ایجنٹ ہے جسے آپ کام کرتے چھوڑ سکتے ہیں۔ اسی لیے جو اکاؤنٹ اسے چلاتا ہے اور سرور پر موجود اس کے اسناد، یہاں کسی بھی واحد سیٹنگ سے زیادہ اہم ہیں۔

ضروریات اور حقیقی مشکلات

• ایک نیا Ubuntu 24.04 KVM VPS جس میں root یا sudo دسترسی ہو۔ کوئی بھی KVM پلان کام کرے گا؛ CLI خود ہلکا ہے، آرام کی حالت میں چند سو MB RAM استعمال کرتا ہے۔
• Node.js 20 یا اس سے نیا ورژن۔ یہ ایک سخت ورژن حد ہے، اور ڈسٹریبیوشن کا پیکج اس سے پرانا ہے — اگلا سیکشن دیکھیں۔
• Google کے APIs کی طرف outbound HTTPS (port 443)۔ کسی بھی inbound port کی ضرورت نہیں؛ یہ ایک کلائنٹ ہے، سرور نہیں، اس لیے آپ کو اس کے لیے فائر وال میں کوئی سوراخ نہیں کھولنا۔
• ایسی تصدیق کا طریقہ جس کے لیے سرور پر براؤزر کی ضرورت نہ ہو: یا تو Google AI Studio سے Gemini API key، یا اپنی مشین پر براؤزر تک واپس SSH tunnel۔ API key والا راستہ اسکرپٹس اور بغیر نگرانی کے چلنے والے کاموں کے لیے بہترین ہے۔
• Docker یا Podman، صرف اگر آپ --sandbox isolation چاہتے ہیں۔ یہ اختیاری ہے، آخر میں بیان کیا گیا ہے۔

وہ مسئلہ جو ہر کسی کو پریشان کرتا ہے: gemini کا پہلی بار چلنے والا دوستانہ لاگ ان فلو ڈیسک ٹاپ کے لیے بنایا گیا ہے۔ یہ براؤزر کھولنے کی کوشش کرتا ہے، اور ہیڈ لیس سرور پر یا تو ناکام ہو جاتا ہے یا ایسا لنک دیتا ہے جو کام نہیں کرتا۔ شروع کرنے سے پہلے تصدیق کا راستہ طے کر لیں۔

Node: ڈسٹرو پیکیج بہت پرانا ہے

Ubuntu 24.04 اپنی ذخیروں میں Node 18.19.1 فراہم کرتا ہے، جو npm 9.2.0 کے ساتھ آتا ہے۔ Gemini CLI کا package.json engines: { node: ">=20" } کا اعلان کرتا ہے، اور npm بذات خود اس میچنگ نہ ہونے کو روک نہیں کرتا — یہ بہرحال انسٹال کر دیتا ہے اور ایک وارننگ پرنٹ کرتا ہے جس میں اس فرق کا ذکر ہوتا ہے:

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '@google/gemini-cli@0.50.0',
npm WARN EBADENGINE   required: { node: '>=20' },
npm WARN EBADENGINE   current: { node: 'v18.19.1', npm: '9.2.0' }
npm WARN EBADENGINE }

اس وارننگ کو نظر انداز کریں تو CLI ایک غیر معاون رن ٹائم پر چلے گا، جہاں یہ خراب کام کرے گا یا کریش ہو جائے گا جیسے ہی اسے کوئی Node 20+ API ملے گا جس کے موجود ہونے کی وہ توقع کرتا ہے۔ Node 18 اپریل 2025 میں اپنی زندگی کے اختتام کو پہنچ چکا ہے، لہٰذا یہ کسی بھی صورت میں ایک مسدود راستہ ہے۔ CLI انسٹال کرنے سے پہلے ایک موجودہ LTS انسٹال کریں۔ دو صاف راستے NodeSource (ایک سسٹم وائڈ سائنڈ apt ریپو) یا nvm (ایک فی یوزر ورژن مینیجر) ہیں۔ کوئی ایک منتخب کریں۔

NodeSource، اگر آپ چاہتے ہیں کہ Node اس باکس پر ہر یوزر کے لیے دستیاب ہو:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

node --version کو v20.x یا اس سے زیادہ پرنٹ کرنا چاہیے — v24.x موجودہ فعال LTS ہے۔ موجودہ سیٹ اپ اسکرپٹ کے لیے NodeSource پیج چیک کریں؛ URL میں setup_24.x وہ لائن ہے جسے کسی نئے LTS کی آمد پر اپ ڈیٹ کرنا ہے۔

nvm، اگر آپ Node کو کسی ایک یوزر کے ہوم کے اندر رکھنا چاہیں اور اسے sudo سے کبھی نہ چھیڑیں:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node --version

اس URL میں v0.40.1 اس وقت موجودہ تھا جب یہ لکھا گیا؛ تازہ ریلیز کے لیے nvm کا README چیک کریں اور اسے چلانے سے پہلے ورژن تبدیل کر کے لکھ دیں۔ nvm کا اس کام میں ایک حقیقی فائدہ ہے: یہ Node اور اس کے گلوبل پیکیجز کو ~/.nvm کے تحت انسٹال کرتا ہے، لہٰذا اگلے سیکشن کا گلوبل انسٹال پرمیشن والا مسئلہ پیدا ہی نہیں ہوتا۔ اگر آپ nvm والا راستہ اختیار کرتے ہیں، تو آپ npm-prefix والا مرحلہ چھوڑ سکتے ہیں۔

sudo npm -g کے بغیر CLI انسٹال کریں

لچھکوانے والا کمانڈ sudo npm install -g @google/gemini-cli ہے۔ اسے نہ چلائیں۔ root کی ملکیت والا global prefix ہر بعد کی انسٹالیشن پر اجازت کی خرابیاں پیدا کرتا ہے، اور آپ کے npm کیشے میں root کی ملکیت والی فائلیں چھوڑتا ہے جو مہینوں بعد مسئلہ بنتی ہیں۔ سسٹم Node کے خلاف ایک عام (بغیر sudo کا) npm install -g چلائیں تو آپ کو دوسری ناکامی ملتی ہے:

npm error code EACCES
npm error syscall mkdir
npm error path /usr/lib/node_modules/@google
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@google'

یہ npm کا /usr/lib میں لکھنے کی کوشش ہے، جہاں آپ کا صارف نہیں لکھ سکتا۔ اس کا حل sudo نہیں ہے — بلکہ npm کے global prefix کو آپ کی ہوم ڈائریکٹری کی طرف موڑنا ہے تاکہ global انسٹالیشنیں آپ کی ملکیت والی جگہ پر آئیں:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli
gemini --version

~/.bashrc کا ہونا، نہ کہ ~/.profile، جان بوجھ کر ہے: tmux — جس کے اندر آپ دو سیکشن بعد CLI چلائیں گے — ایک non-login شیل شروع کرتا ہے جو ~/.bashrc کو پڑھتا ہے اور ~/.profile کو نظر انداز کرتا ہے، اس لیے غلط فائل میں PATH لائن چھوڑنے سے gemini بالکل اسی جگہ غائب رہتا ہے جہاں آپ کو اس کی ضرورت ہے۔ gemini --version کا ورژن نمبر چھاپنا ہی مکمل ٹیسٹ ہے۔ اگر آپ کو اس کے بجائے gemini: command not found ملے، تو آپ کا PATH export نافذ نہیں ہوا — خرابی کے طریقے دیکھیں۔ nvm پر، prefix لائنوں کو مکمل طور پر چھوڑ دیں: یہ پہلے ہی globals کو آپ کی ہوم کے تحت انسٹال کرتا ہے۔

اگر آپ نے کسی پہلے وقت میں sudo npm چلایا تھا اور اب Your cache folder contains root-owned files دیکھ رہے ہیں، تو اسے ایک بار sudo chown -R $(id -u):$(id -g) ~/.npm سے درست کریں۔

ہیڈلیس تصدیق کا مسئلہ، اور اس سے کیسے نکلنا

پہلی بار gemini کو انٹرایکٹو طریقے سے چلائیں تو یہ آپ کو اپنے Google اکاؤنٹ سے لاگ ان کرنے کی پیشکش کرتا ہے۔ ڈیسک ٹاپ پر یہ ایک براؤزر ٹیب کھولتا ہے۔ ہیڈلیس VPS پر کوئی براؤزر نہیں ہوتا، اس لیے یہ عمل یا تو ایک localhost URL پرنٹ کرتا ہے جسے آپ سے کھولنے کی توقع ہوتی ہے، یا پھر ایسے ہی ناکام ہو جاتا ہے:

Failed to open browser. Please visit the following URL to authorize:
https://accounts.google.com/o/oauth2/v2/auth?...&redirect_uri=http://localhost:PORT

یہاں پھنسنا redirect_uri=http://localhost:PORT کی وجہ سے ہے۔ چاہے آپ وہ URL اپنے لیپ ٹاپ پر کھولیں اور اس کی منظوری دیں، Google http://localhost:PORT پر ریڈائریکٹ کرتا ہے — یعنی سرور پر localhost، ایک ایسا پورٹ جس تک آپ کے لیپ ٹاپ سے رسائی ممکن نہیں۔ لاگ ان کبھی مکمل نہیں ہوتا۔

اس سے نکلنے کے دو درست طریقے ہیں۔

پہلا طریقہ API کلید کا استعمال ہے، اور یہ سرور کے لیے صحیح ڈیفالٹ ہے۔ Google AI Studio (aistudio.google.com) میں ایک کلید بنائیں اور اسے بطور انوائرنمنٹ ویریبل CLI کو دیں؛ یہ GEMINI_API_KEY کو پڑھتا ہے اور براؤزر کا عمل مکمل طور پر چھوڑ دیتا ہے۔ اب "اسے ہسٹری اور ہر کوئی پڑھ سکنے والی فائلوں سے باہر رکھیں" والا حصہ۔ پرامپٹ پر export GEMINI_API_KEY=AIza... ٹائپ نہ کریں — یہ ~/.bash_history میں کلئیر ٹیکسٹ میں محفوظ ہو جاتا ہے، اور اسے کسی ایسی فائل میں نہ رکھیں جسے دیگر پڑھ سکیں۔ اسے mode-600 فائل میں لکھیں جسے شیل اسٹارٹ پر سورس کرتا ہے:

umask 077
printf 'export GEMINI_API_KEY=%s\n' 'AIzaSyYOUR_KEY_HERE' > ~/.gemini_env
chmod 600 ~/.gemini_env
echo '[ -f ~/.gemini_env ] && . ~/.gemini_env' >> ~/.bashrc
source ~/.bashrc

chmod 600 کا مطلب ہے کہ صرف آپ کا یوزر اس فائل کو پڑھ سکتا ہے۔ printenv GEMINI_API_KEY سے تصدیق کریں کہ کلید انوائرنمنٹ تک پہنچی ہے؛ اگر وہ کچھ بھی پرنٹ نہ کرے، تو CLI براؤزر کے عمل کی طرف لوٹ جاتا ہے اور ناکام ہو جاتا ہے۔ یہ ~/.gemini/ میں .env فائل بھی پڑھتا ہے اگر آپ اس ترتیب کو پسند کرتے ہیں — وہی اصول، لہذا chmod 600 ~/.gemini/.env۔

دوسرا طریقہ ذاتی Google اکاؤنٹ لاگ ان (اور اس کے فری ٹیئر) کو برقرار رکھتا ہے، OAuth کال بیک کو آپ کے لیپ ٹاپ تک ٹنل کر کے۔ مسئلہ یہ ہے کہ CLI کا لوپ بیک سرور ہر بار ایک رینڈم پورٹ بائنڈ کرتا ہے، اس لیے فوروارڈ کرنے کے لیے کوئی مستحکم پورٹ نہیں ہوتا جب تک کہ آپ پہلے OAUTH_CALLBACK_PORT انوائرنمنٹ ویریبل کے ساتھ اسے مقرر نہ کریں، پھر بالکل اسی پورٹ کو فوروارڈ کریں:

# from your laptop, forward the callback port into the SSH session:
ssh -L 8085:localhost:8085 user@your-server
# then, on the server, pin the callback to the same port and start the CLI:
export OAUTH_CALLBACK_PORT=8085
gemini

CLI براؤزر نہیں کھول سکتا، اس لیے یہ تصدیق کا URL پرنٹ کرتا ہے؛ اسے اپنے لیپ ٹاپ براؤزر میں کھولیں، منظوری دیں، اور جب Google http://localhost:8085/... پر ریڈائریکٹ کرتا ہے تو SSH فوروارڈ اسے VPS پر لوپ بیک سرور تک پہنچا دیتا ہے اور لاگ ان مکمل ہو جاتا ہے۔ پورٹ کو مقرر نہ کریں تو یہ ہر بار ایک نئے رینڈم پورٹ پر آتا ہے، جسے کوئی بھی پہلے سے سیٹ اپ شدہ ssh -L پکڑ نہیں سکتا۔ یہ کام کرتا ہے، لیکن اس کے لیے آپ کو براؤزر کے سامنے بیٹھنا پڑتا ہے، اس لیے یہ اسکرپٹس کے لیے موزوں نہیں۔ جو کچھ بھی آپ چلتا چھوڑیں، اس کے لیے API کلید استعمال کریں۔

AI Studio کے بجائے Vertex AI یا Google Cloud پروجیکٹ کے لیے، GOOGLE_API_KEY کو GOOGLE_GENAI_USE_VERTEXAI=true کے ساتھ سیٹ کریں، یا Code Assist لائسنس کے لیے GOOGLE_CLOUD_PROJECT — وہی انوائرنمنٹ ویریبل کا اصول، وہی mode-600 فائل۔

اسے tmux کے اندر چلائیں تاکہ منقطع ہونے والا SSH سیشن اسے ختم نہ کرے

آپ جو gemini پروسیس براہ راست اپنے SSH شیل سے چلاتے ہیں وہ اسی شیل کا چائلڈ ہوتا ہے۔ کنکشن ٹوٹنے پر — لیپ ٹاپ بند ہونا، Wi-Fi منقطع ہونا، یا idle ٹائم آؤٹ — sshd sudo-terminal کو ختم کر دیتا ہے، شیل کو SIGHUP موصول ہوتا ہے، اور یہ باری باری CLI کو بھی ہینگ اپ کر دیتا ہے۔ فائلوں میں ترمیم کا کوئی کام جو دس منٹ میں آگے بڑھ چکا ہو، اس کے ساتھ ہی مر جاتا ہے، اور دوبارہ کنیکٹ ہونے پر بحال کرنے کے لیے کوئی پروسیس نہیں بچتی۔

tmux اسے اس طرح ٹھیک کرتا ہے کہ یہ شیل کا مالک بن جاتا ہے، sshd کے بجائے۔ یہ بالکل وہی پیٹرن ہے جو کسی ریموٹ VPS پر tmux کے اندر AI کوڈنگ ایجنٹ چلانے کا ہے، اور یہ یہاں بھی بالکل ایسے ہی کام کرتا ہے:

sudo apt install -y tmux
tmux new -A -s gemini
# inside the session:
gemini
# detach with Ctrl-b then d — the task keeps running
# reconnect later from any machine:
tmux attach -t gemini

tmux new -A -s gemini gemini نامی سیشن سے منسلک ہو جاتا ہے اگر وہ موجود ہو، اور موجود نہ ہونے کی صورت میں اسے بنا دیتا ہے۔ لہٰذا یہ وہ واحد کمانڈ ہے جو ہر لاگ ان کے فوراً بعد چلانی چاہیے۔ اس کے اندر کا شیل منقطع tmux سرور سے تعلق رکھتا ہے، آپ کے SSH سیشن سے نہیں، اس لیے کنکشن منقطع ہونے کے باوجود CLI کام کرتا رہتا ہے۔ دوبارہ کنیکٹ ہوں، منسلک ہوں، اور آپ اسی scrollback میں واپس ہوں۔

غیر انٹرایکٹو، اسکرپٹڈ چلانے کے لیے، Gemini CLI میں ہیڈلیس موڈ موجود ہے: gemini -p "summarise the failing tests in this repo" جواب طبع کرتا ہے اور باہر نکل جاتا ہے، اور --output-format json مشین ریڈ ایبل آؤٹ پٹ فراہم کرتا ہے جسے کہیں اور پائپ کیا جا سکے۔ API کلید کے ساتھ ہیڈلیس موڈ بالکل وہی ہے جو آپ کو tmux سیشن کے اندر طویل بیچ جاب چلانے، یا cron انٹری سے چلانے کے لیے درکار ہے — ایک احتیاط کے ساتھ: cron جاب آپ کی کسی بھی لاگ ان فائل کو سورس نہیں کرتی، اس لیے crontab لائن کو اپنا GEMINI_API_KEY دیں (یا کمانڈ کو ~/.gemini_env سورس کرنے دیں)، ورنہ CLI براؤزر فلو پر واپس چلا جاتا ہے اور ناکام ہو جاتا ہے۔

سینڈ باکسنگ اور اجازات ایک ایسے سسٹم پر جو پروڈکشن بھی چلاتا ہے

شیل تک رسائی رکھنے والا کوئی ایجنٹ دراصل شیل ہی ہوتا ہے۔ Gemini CLI کمانڈز چلا سکتا ہے، اور بطورِ پیش فرض یہ ہر خطرناک کمانڈ سے پہلے اجازت طلب کرتا ہے — لیکن لوگ --yolo (ہر ٹول کال کی خودکار منظوری) کا سہارا لیتے ہیں، اور پھر یہ فائلیں حذف کر سکتا ہے، git پر پش کر سکتا ہے، یا اندرونی سروسز تک اس یوزر کی مکمل طاقت کے ساتھ رسائی حاصل کر سکتا ہے جس کے طور پر یہ چلتا ہے۔ ایک ایسے سسٹم پر جو پروڈکشن بھی چلاتا ہے، یہ ایک حقیقی تباہی کا دائرہ ہے، فرضی نہیں۔

تین کنٹرولز، اس ترتیب میں کہ وہ آپ کو کتنا فائدہ دیتے ہیں:

• اسے ایک مخصوص، غیر مرتبط یوزر کے طور پر چلائیں۔ نہ root، نہ sudo کا رکن۔ ایک agent یوزر بنائیں جس کا اپنا ہوم ہو، Node اور CLI وہاں انسٹال کریں، اور غلط پڑھی گئی ہدایت اس اکاؤنٹ تک ہی محدود رہے گی۔ یہ واحد سب سے زیادہ قابلِ قدر فیصلہ ہے۔
• پروڈکشن کی اسناد کو سسٹم سے دور رکھیں۔ کوئی prod ~/.aws/credentials نہیں، پروڈکشن سے کوپی کیا گیا کوئی .env نہیں، اور ایسا کوئی ڈیٹا بیس پاس ورڈ نہیں جس میں کسی بھی اہم چیز تک لکھنے کی رسائی ہو۔ اسے staging یا صرف پڑھنے کے قابل اسناد دیں۔
• بلٹ اِن سینڈ باکس استعمال کریں۔ Docker یا Podman انسٹال ہونے کی صورت میں، gemini --sandbox (یا GEMINI_SANDBOX=docker) ایجنٹ کی ٹول کالز کو ہوسٹ فائل سسٹم اور نیٹ ورک سے الگ تھلگ کنٹینر کے اندر چلاتا ہے۔ یہ غیر مرتبط یوزر کا متبادل نہیں ہے، لیکن جب ایک ہی VPS حقیقی کام کر رہا ہو تو یہ ایک مضبوط دوسری پرت ہے۔

اگر آپ Gemini CLI کو دیگر سیلف ہوسٹڈ ٹولز کے ساتھ چلا رہے ہیں — جیسے ایک ایک ہی VPS پر ایجنٹ کو ٹولز فراہم کرنے والا MCP سرور — تو ہر اضافی صلاحیت کو ایجنٹ کی پہنچ کے لیے مزید سطح سمجھیں، اور اسے دیے گئے ٹوکنز کا دائرہ بالکل ایک ہی کام تک محدود رکھیں۔

کوٹہ، لاگت، اور آپ کا منتخب کردہ تصدیقی راستہ

تصدیقی راستہ طے کرتا ہے کہ آپ کی بلنگ کیسے ہوگی۔ ذاتی Google اکاؤنٹ (OAuth راستہ) مفت Gemini Code Assist ٹیئر استعمال کرتا ہے، جس میں فی منٹ اور فی دن حقیقی حدود ہیں۔ حدود سے تجاوز کرنے پر درخواستیں ریٹ-لimit ایرر دیں گی جب تک کہ ونڈو ری سیٹ نہ ہو۔ AI Studio سے حاصل کردہ API کلید مفت ٹیئر کی ہو سکتی ہے یا پروجیکٹ کے لحاظ سے بلڈ ہو سکتی ہے۔ بلڈ کلید حدود کو بڑھاتی ہے اور فی ٹوکن چارج کرتی ہے۔ Vertex اور Cloud-project تصدیق Google Cloud کے ذریعے بل ہوتی ہے۔

دو عملی نکات۔ بغیر نگرانی والا ایجنٹ لوپ میں کوٹہ جلدی ختم کر سکتا ہے۔ اس لیے پہلی چند بار اس پر نظر رکھیں قبل از اسے cron job کے حوالے کرنا۔ اور اگر سرور سائڈ ماڈل کا آپ کا مقصد رازداری یا بے میٹرڈ انفرنس ہے Google کے ہوسٹڈ ماڈلز کے بجائے، تو یہ ایک مختلف ٹول ہے۔ VPS پر Ollama کے ساتھ اوپن LLM کو سیلف-ہوسٹ کرنا ویٹس اور پرامپٹس کو آپ کے اپنے باکس پر رکھتا ہے، لیکن اس کی قیمت Gemini سے کہیں چھوٹے ماڈل کو چلانا ہے۔

اپ ڈیٹ رکھنا

Gemini CLI کثرت سے ریلیز ہوتا ہے۔ چونکہ آپ نے اسے صارف کی ملکیت والے prefix میں انسٹال کیا ہے، اپ ڈیٹس کے لیے sudo کی کبھی ضرورت نہیں ہوتی:

npm install -g @google/gemini-cli@latest
gemini --version

ریلیز چینلز موجود ہیں: @latest مستحکم ہے، @preview ہفتہ وار پیش نظارہ ہے، @nightly انتہائی جدید ورژن ہے — کسی بھی ایسی چیز پر جس پر آپ انحصار کرتے ہیں اسے @latest پر مقفل رکھیں۔ nvm پر، عالمی پیکیجز فعال Node ورژن کے تحت موجود ہوتے ہیں، لہذا Node سوئچ کرنے کے لیے nvm use کے بعد آپ کو CLI دوبارہ انسٹال کرنے کی ضرورت پڑ سکتی ہے۔ ہر معمولی پیچ کے پیچھے بھاگنے کے بجائے ریلیز نوٹس پڑھیں۔

ناکامی کے طریقے، مع عین الفاظ

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }، پھر CLI کا رن ٹائم پر کریش ہونا۔ Node کا ورژن بہت پرانا ہے — ڈسٹرو کا 18.19.1 ہے، جو کہ زندگی کے اختتام سے بھی آگے بڑھ چکا ہے۔ NodeSource یا nvm سے Node 20+ انسٹال کریں، node --version سے تصدیق کریں، اور اگر آپ کے پاس متعدد Node انسٹال ہیں، تو چیک کریں کہ which node نئے والے کی طرف اشارہ کر رہا ہے نہ کہ /usr/bin/node کی طرف۔

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'۔ روٹ کی ملکیت والے prefix میں عالمی انسٹالیشن۔ اسے sudo سے نہ چلائیں — npm config set prefix ~/.npm-global سیٹ کریں، ~/.npm-global/bin کو PATH پر رکھیں، اور اپنے عام یوزر کے طور پر دوبارہ انسٹال کریں۔ اگر کسی پچھلے sudo npm نے روٹ کی ملکیت والے کیش فائلز (Your cache folder contains root-owned files) چھوڑے ہیں، تو sudo chown -R $(id -u):$(id -g) ~/.npm چلائیں۔

Failed to open browser، رکا ہوا لاگ ان، یا ایک redirect_uri=http://localhost:PORT جس تک آپ نہیں پہنچ سکتے۔ OAuth فلو کو براؤزر درکار ہے جو سرور کے پاس نہیں ہے، اور اس کا localhost کال بیک سرور کی طرف اشارہ کرتا ہے، آپ کے لیپ ٹاپ کی طرف نہیں۔ API-key والا راستہ استعمال کریں (GEMINI_API_KEY)، یا OAUTH_CALLBACK_PORT کو پن کریں، اسے SSH پر ssh -L سے فارورڈ کریں، اور URL کو مقامی طور پر کھولیں۔

SSH ٹوٹنے پر پروسیس غائب ہو گئی۔ آپ نے gemini کو براہ راست SSH شیل سے چلایا، لہذا وہ اس شیل کا چائلڈ تھا اور ڈسکنیکٹ پر pty کے ساتھ مر گیا۔ بحال کرنے کے لیے کچھ نہیں۔ ہر سیشن کا آغاز tmux new -A -s gemini سے کریں اور CLI کو اس کے اندر چلائیں۔

کلید سیٹ ہونے کے باوجود توثیق اب بھی ناکام ہے — CLI اپنے auth پکر پر واپس آ جاتا ہے، یا ایک درخواست HTTP 400 کے ساتھ API key not valid واپس کرتی ہے۔ کلید اس ماحول میں موجود نہیں ہے جسے CLI دیکھتا ہے۔ printenv GEMINI_API_KEY سے تصدیق کریں؛ اگر یہ خالی ہے، تو آپ کا ~/.gemini_env کبھی سورس نہیں ہوا — چیک کریں کہ لائن ~/.bashrc میں موجود ہے، جسے انٹرایکٹو شیلز (tmux سمیت) پڑھتے ہیں لیکن cron اور دیگر غیر انٹرایکٹو شیلز نہیں پڑھتے۔ کلید ویلیو کے اندر کوئی بھٹکا ہوا اسپیس یا کوٹیشن بھی API key not valid پیدا کرتا ہے۔

429 / RESOURCE_EXHAUSTED / ریٹ-لimit پیغام۔ آپ نے اس ٹائر کا کوٹہ مکمل کر لیا ہے جو آپ کی توثیق استعمال کرتی ہے۔ ونڈو کے ری سیٹ ہونے کا انتظار کریں، ایجنٹ کو سست کریں، یا بلڈ API کلید پر منتقل ہوں۔ ریٹری لوپ میں پھنسا ہوا ایجنٹ بار بار اسے ہٹ کرتا رہتا ہے — اسے روکیں اور چیک کریں کہ یہ کیا کر رہا ہے۔

FAQ

میں ہیڈلیس سرور پر Gemini CLI کو کیسے authenticate کروں؟

API key استعمال کریں، browser login نہیں۔ Google AI Studio میں key بنائیں، اسے mode-600 file میں رکھیں جسے آپ کا shell source کرتا ہے (export GEMINI_API_KEY=...)، اور CLI پوری طرح OAuth browser flow کو چھوڑ دیتا ہے۔ اگر آپ خاص طور پر personal-account free tier چاہتے ہیں، تو loopback port کو OAUTH_CALLBACK_PORT=8085 کے ساتھ pin کریں، اسے ssh -L 8085:localhost:8085 user@server کے ساتھ اپنے laptop پر forward کریں، اور printed URL کو locally open کریں — لیکن اس کے لیے آپ کا browser پر موجود ہونا ضروری ہے، اس لیے یہ scripts کے لیے موزوں نہیں ہے۔

npm global install کیوں sudo چاہتا ہے، اور میں اس سے کیسے بچوں؟

اس لیے کہ npm کا default global prefix /usr/lib/node_modules ہے، جس پر آپ کا user write نہیں کر سکتا، اس لیے ایک سادہ npm install -g EACCES کے ساتھ fail ہو جاتا ہے۔ غلط حل sudo npm -g ہے، جو root-owned files چھوڑتا ہے جو بعد کی installs کو خراب کر دیتے ہیں۔ درست حل prefix کو آپ کے home کی طرف pointing کرنا ہے (npm config set prefix ~/.npm-global) اور اس کا bin PATH میں add کرنا ہے، یا nvm استعمال کریں، جو global packages کو آپ کے home کے تحت automatically install کرتا ہے۔

میں disconnect کرنے کے بعد Gemini CLI کو چلتا کیسے رکھوں؟

اسے tmux کے اندر چلائیں۔ آپ کے SSH shell سے شروع ہونے والا process connection گرنے پر مر جاتا ہے کیونکہ وہ اس shell کا child ہے؛ tmux shell کو ایک detached server کے تحت چلاتا ہے جو disconnect سے بچ جاتا ہے۔ tmux new -A -s gemini استعمال کریں، اس کے اندر gemini چلائیں، Ctrl-b d کے ساتھ detach کریں، اور بعد میں tmux attach -t gemini کے ساتھ reattach کریں۔

کیا production box پر Gemini CLI چلانا محفوظ ہے؟

صرف احتیاط کے ساتھ، کیونکہ shell access والا agent وہ سب کچھ کر سکتا ہے جو وہ user کر سکتا ہے جس کے طور پر وہ run ہو رہا ہے۔ اسے ایک dedicated unprivileged user کے طور پر چلائیں جس میں sudo نہ ہو، production credentials کو machine سے دور رکھیں، --yolo auto-approval سے بچیں، اور tool calls کو host سے isolate کرنے کے لیے --sandbox (Docker یا Podman) استعمال کریں۔ جس account کے تحت یہ run ہوتا ہے، وہ آپ کے set کردہ کسی بھی single flag سے زیادہ اہم ہے۔

کیا مجھے Gemini CLI کے لیے کوئی firewall ports open کرنے کی ضرورت ہے؟

نہیں۔ یہ ایک client ہے جو Google کی APIs کو outbound HTTPS calls کرتا ہے، اس لیے اسے outbound port 443 درکار ہے لیکن کوئی inbound ports نہیں۔ اگر آپ OAuth tunnel استعمال کرتے ہیں، تو pinned callback port (مثلاً 8085) localhost پر موجود ہوتا ہے اور آپ کے SSH forward کے ذریعے پہنچا جاتا ہے، کسی open inbound port سے نہیں۔ inbound locked down رکھیں۔