Headless VPS पर Gemini CLI कैसे सेटअप करें

आप क्या बना रहे हैं

एक हमेशा चालू रहने वाला Gemini CLI जिसे आप अपने सर्वर पर होस्ट करते हैं। इसे SSH के माध्यम से एक्सेस किया जा सकता है और यह लंबे एजेंट कार्यों को चला सकता है जो आपके लैपटॉप बंद करने के बाद भी चलते रहते हैं। इसका इंस्टॉलेशन केवल तीन कमांड्स में हो जाता है। मेहनत वहां लगती है जहाँ डेस्कटॉप वातावरण की अपेक्षा की जाती है: Google का CLI लॉग इन करने के लिए ब्राउज़र खोलना चाहता है, जबकि आपके सर्वर पर ब्राउज़र नहीं है। इसलिए, इस गाइड का अधिकांश हिस्सा 'हेडलेस' (headless) सेटअप पर केंद्रित है। इसमें शामिल हैं: डिस्ट्रो द्वारा न दिया गया Node का नवीनतम वर्ज़न, एक ग्लोबल npm इंस्टॉलेशन जिसे root की आवश्यकता नहीं है, बिना ब्राउज़र के API key के साथ ऑथेंटिकेशन (जिसे आप अपनी shell history से दूर रखते हैं), और tmux ताकि SSH सेशन डिस्कनेक्ट होने पर भी आपका काम बंद न हो।

Gemini CLI एक ओपन-सोर्स (Apache-2.0) Node प्रोग्राम (@google/gemini-cli) है जो Google के Gemini मॉडल्स के साथ संवाद करता है। यह फाइलों को पढ़ और लिख सकता है, शेल कमांड्स चला सकता है और वर्किंग डायरेक्टरी में टूल्स का उपयोग कर सकता है। एक VPS पर यह एक छोटा, हमेशा उपलब्ध रहने वाला एजेंट है जिसे आप काम पर छोड़ सकते हैं। यही कारण है कि जिस अकाउंट से यह चलता है और जो क्रेडेंशियल्स सर्वर पर मौजूद होते हैं, वे यहाँ दी गई किसी भी अन्य सेटिंग से अधिक महत्वपूर्ण हैं।

आवश्यक शर्तें और महत्वपूर्ण सावधानियां

• root या sudo एक्सेस के साथ एक नया Ubuntu 24.04 KVM VPS। कोई भी KVM प्लान काम करेगा; CLI स्वयं बहुत हल्का है और idle रहने पर कुछ सौ MB RAM का उपयोग करता है।
• Node.js 20 या उससे नया संस्करण। यह एक अनिवार्य न्यूनतम संस्करण है, और डिस्ट्रो पैकेज इससे पुराना है, इसलिए अगला भाग देखें। Node 20 का जीवनकाल 30 अप्रैल, 2026 को समाप्त हो गया है, इसलिए 24 इंस्टॉल करें।
• Google के APIs के लिए आउटबाउंड HTTPS (port 443)। किसी इनबाउंड पोर्ट की आवश्यकता नहीं है; यह एक क्लाइंट है, सर्वर नहीं, इसलिए इसके लिए firewall में कोई छेद खोलने की जरूरत नहीं है।
• प्रमाणीकरण का एक तरीका जिसके लिए सर्वर पर ब्राउज़र की आवश्यकता न हो: या तो Google AI Studio से एक सशुल्क Gemini API key, या Google sign-in, जिसमें headless बॉक्स पर आपको टर्मिनल में एक कोड पेस्ट करना होता है। API-key वाला तरीका स्क्रिप्ट और unattended runs के लिए सबसे उपयुक्त है।
• Docker या Podman, केवल तभी यदि आप --sandbox आइसोलेशन चाहते हैं। यह वैकल्पिक है और अंत के पास कवर किया गया है।

जो समस्या आजकल सभी को परेशान करती है वह अकाउंट है, ब्राउज़र नहीं। Google ने 19 मई, 2026 को घोषणा की कि 18 जून, 2026 से Gemini CLI, Google AI Pro और Ultra सब्सक्राइबर्स तथा मुफ्त में इसका उपयोग करने वाले किसी भी व्यक्ति के लिए अनुरोधों को पूरा करना बंद कर देगा, और यह उन उपयोगकर्ताओं को अपने प्रतिस्थापन, Antigravity CLI (agy) की ओर निर्देशित करता है। Gemini CLI अभी भी सशुल्क Gemini API keys, Gemini Enterprise Agent Platform API keys, और किसी संगठन के Gemini Code Assist Standard या Enterprise लाइसेंस के साथ काम करता है। शुरू करने से पहले प्रमाणीकरण का रास्ता तय कर लें।

नोट: डिस्ट्रो पैकेज बहुत पुराना है

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

CLI की आवश्यकताओं को पूरा करने के लिए node --version को v20.x या उससे अधिक प्रिंट करना चाहिए, लेकिन Node 20 का एंड-ऑफ-लाइफ 30 अप्रैल, 2026 को हो चुका है, इसलिए v24.x (वर्तमान सक्रिय LTS) का लक्ष्य रखें। Node 26 के 28 अक्टूबर, 2026 को सक्रिय 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 बाद के हर इंस्टॉलेशन पर permission errors पैदा करता है और आपके npm cache में 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 में लिखने की कोशिश कर रहा है, जिसे आपका user नहीं लिख सकता। इसका समाधान sudo नहीं है, बल्कि npm के global prefix को अपनी home directory की ओर इंगित करना है ताकि 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 shell शुरू करता है जो ~/.bashrc को पढ़ता है और ~/.profile को छोड़ देता है। इसलिए गलत फाइल में PATH लाइन होने से gemini ठीक उसी जगह अदृश्य हो जाता है जहाँ आपको इसकी आवश्यकता है। gemini --version का वर्ज़न नंबर प्रिंट करना ही पूरा टेस्ट है। यदि इसके बजाय आपको gemini: command not found मिलता है, तो आपका PATH export लागू नहीं हुआ है, विफलता के प्रकार देखें। nvm पर, prefix लाइनों को पूरी तरह छोड़ दें: यह पहले से ही globals को आपके home के अंदर इंस्टॉल करता है।

यदि आपने पहले किसी बिंदु पर sudo npm चलाया था और अब Your cache folder contains root-owned files दिखाई देता है, तो इसे sudo chown -R $(id -u):$(id -g) ~/.npm के साथ एक बार ठीक करें।

Headless auth की समस्या और इससे निपटने के उपाय

पहली बार gemini को इंटरैक्टिव तरीके से चलाने पर यह आपको Google अकाउंट से लॉग इन करने का विकल्प देता है। डेस्कटॉप पर यह एक ब्राउज़र टैब खोलता है। Headless Linux VPS पर CLI पहले डिस्प्ले की जाँच करता है, और जब DISPLAY, WAYLAND_DISPLAY या MIR_SOCKET में से कोई भी सेट नहीं होता, तो यह ब्राउज़र लॉन्च करने का प्रयास नहीं करता है। यह एक साइन-इन लिंक प्रिंट करता है और आपके द्वारा कोड पेस्ट करने की प्रतीक्षा करता है:

Please visit the following URL to authorize the application:

https://accounts.google.com/o/oauth2/v2/auth?...

Enter the authorization code:

यह फ्लो सामान्य SSH पर काम करता है, लेकिन इसके लिए हर बार आपको ब्राउज़र की आवश्यकता होती है, और 18 जून, 2026 से यह केवल तभी काम करता है यदि आपका Google अकाउंट वह है जिसे Gemini CLI अभी भी सपोर्ट करता है।

इससे निपटने के दो सही तरीके हैं।

पहला तरीका API key है, और सर्वर के लिए यही डिफ़ॉल्ट विकल्प सबसे उचित है। Google AI Studio (aistudio.google.com) पर एक ऐसे प्रोजेक्ट में की (key) बनाएँ जहाँ बिलिंग चालू हो, क्योंकि Gemini CLI अब मुफ्त उपयोग की सुविधा नहीं देता है। इसे environment variable के रूप में CLI को दें; यह GEMINI_API_KEY को पढ़ता है और ब्राउज़र फ्लो को पूरी तरह छोड़ देता है। अब "इसे हिस्ट्री और world-readable फाइलों से दूर रखें" वाले हिस्से पर ध्यान दें। प्रॉम्प्ट पर 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 के साथ पुष्टि करें कि की (key) एनवायरनमेंट तक पहुँच गई है; यदि यह कुछ भी प्रिंट नहीं करता है, तो CLI की (key) का उपयोग करने के बजाय अपने auth picker पर वापस चला जाएगा। यदि आप उस लेआउट को पसंद करते हैं, तो यह ~/.gemini/ में .env फाइल को भी पढ़ता है, नियम वही है, इसलिए chmod 600 ~/.gemini/.env का पालन करें।

दूसरा तरीका स्वयं Google साइन-इन है, जिसके लिए headless बॉक्स पर किसी टनल या ओपन पोर्ट की आवश्यकता नहीं होती है। 18 जून, 2026 से यह मुख्य रूप से किसी संगठन के Gemini Code Assist Standard या Enterprise लाइसेंस के लिए उपयोगी है (GOOGLE_CLOUD_PROJECT को भी सेट करें); मुफ्त पर्सनल अकाउंट और Google AI Pro या Ultra सब्सक्रिप्शन अब सपोर्टेड नहीं हैं। सामान्य SSH सेशन पर CLI शुरू करें और Sign in with Google चुनें:

gemini

प्रिंट किए गए URL को अपने लैपटॉप ब्राउज़र में कॉपी करें और अनुमति दें। Google https://codeassist.google.com/authcode पर रीडायरेक्ट करता है, जो आपको एक ऑथराइजेशन कोड दिखाता है; इसे VPS पर Enter the authorization code: प्रॉम्प्ट पर पेस्ट करें और लॉगिन पूरा हो जाएगा। सर्वर पर कोई भी चीज़ कॉलबैक की प्रतीक्षा नहीं करती है, इसलिए पिन करने के लिए कोई पोर्ट नहीं है और न ही ssh -L सेट करने की आवश्यकता है। OAUTH_CALLBACK_PORT केवल उस लूपबैक फ्लो के लिए मायने रखता है जिसका उपयोग CLI तब करता है जब उसे डिस्प्ले मिलता है। यदि आपने X11 फॉरवर्डिंग (ssh -X) के साथ कनेक्ट किया है, तो DISPLAY सेट हो जाता है और CLI उस लूपबैक फ्लो को अपना लेता है, जिसमें सर्वर पर http://127.0.0.1:PORT/oauth2callback पर रीडायरेक्ट होता है; पेस्ट-ए-कोड फ्लो को फोर्स करने के लिए NO_BROWSER=true gemini चलाएँ। यह काम करता है, लेकिन इसके लिए आपको ब्राउज़र के सामने बैठना पड़ता है, इसलिए यह स्क्रिप्ट के लिए उपयुक्त नहीं है। जो कुछ भी आप बैकग्राउंड में चलाना चाहते हैं, उसके लिए API key का उपयोग करें।

AI Studio के बजाय Vertex AI या Google Cloud प्रोजेक्ट के लिए, GOOGLE_GENAI_USE_VERTEXAI=true के साथ GOOGLE_API_KEY सेट करें, या Code Assist लाइसेंस के लिए GOOGLE_CLOUD_PROJECT सेट करें। एनवायरनमेंट-वेरिएबल का अनुशासन और mode-600 फाइल का नियम यहाँ भी समान है।

इसे tmux के अंदर चलाएं ताकि SSH session कटने पर यह बंद न हो

SSH shell से सीधे लॉन्च की गई gemini प्रक्रिया उस shell की child होती है। यदि connection टूट जाए, laptop बंद हो जाए, Wi-Fi कट जाए या idle timeout हो जाए, तो sshd pseudo-terminal को बंद कर देता है। इसके परिणामस्वरूप shell को SIGHUP प्राप्त होता है और वह CLI को बंद कर देता है। फाइलों को edit करने का दस मिनट का काम भी इसके साथ ही नष्ट हो जाता है और reconnect करने पर कोई प्रक्रिया recovery के लिए उपलब्ध नहीं होती।

tmux इस समस्या को हल करता है क्योंकि यह shell का स्वामित्व ले लेता है, न कि sshd का। यह प्रक्रिया remote VPS पर tmux के अंदर AI coding agent चलाने के समान ही है, और यहाँ भी यह बिल्कुल वैसे ही काम करती है:

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 नाम का session मौजूद हो तो उससे जुड़ जाता है और यदि न हो तो उसे बना देता है, इसलिए हर login के तुरंत बाद चलाने के लिए यह एकमात्र command है। इसके अंदर की shell detached tmux server से संबंधित होती है, न कि आपके SSH session से, इसलिए connection टूटने पर भी CLI काम करना जारी रखती है। Reconnect करें, attach करें, और आप वापस उसी scrollback पर आ जाएंगे। यदि आप एक ही box पर कई agent sessions चलाते हैं, हर tmux session में एक, तो यहाँ उनके बीच आपस में बात करने का कोई तरीका नहीं है, जो Claude Code से अलग है, जहाँ एक ही VPS पर एक session दूसरे को text भेज सकता है, इसलिए हर Gemini job को स्वतंत्र रखें या disk पर मौजूद फाइलों के माध्यम से उन्हें coordinate करें।

Non-interactive, scripted runs के लिए, Gemini CLI में एक headless mode होता है: gemini -p "summarise the failing tests in this repo" उत्तर print करके exit हो जाता है, और --output-format json अन्य जगह pipe करने के लिए machine-readable output देता है। API key के साथ headless mode वही है जो आप एक लंबी batch job चलाने वाले tmux session के अंदर चाहते हैं, या जिसे cron entry से चलाया जाता है, बस एक सावधानी के साथ: cron job आपकी किसी भी login file को source नहीं करती है, इसलिए crontab line को अपना GEMINI_API_KEY दें (या command को ~/.gemini_env source करने के लिए कहें), अन्यथा credentials की कमी के कारण run विफल हो जाएगा।

प्रोडक्शन चलाने वाले सर्वर पर सैंडबॉक्सिंग और अनुमतियाँ

शेल एक्सेस वाला एक एजेंट वास्तव में एक शेल ही होता है। Gemini CLI कमांड चला सकता है, और डिफ़ॉल्ट रूप से यह प्रत्येक जोखिम भरे कमांड से पहले पूछता है, लेकिन लोग --yolo (प्रत्येक टूल कॉल को स्वतः स्वीकृत करना) का उपयोग करने लगते हैं। इसके बाद यह फ़ाइलों को हटा सकता है, git पर पुश कर सकता है, या जिस उपयोगकर्ता के रूप में यह चल रहा है, उसके पूर्ण अधिकारों के साथ आंतरिक सेवाओं को प्रभावित कर सकता है। ऐसे सर्वर पर जो प्रोडक्शन का काम भी कर रहा हो, यह एक वास्तविक खतरा है, न कि केवल काल्पनिक।

तीन नियंत्रण, उनके लाभ के क्रम में:

• इसे एक समर्पित, अनप्रिविलेज्ड (unprivileged) उपयोगकर्ता के रूप में चलाएँ। न तो root के रूप में, न ही sudo के सदस्य के रूप में। एक agent उपयोगकर्ता बनाएँ जिसका अपना home हो, वहाँ Node और CLI इंस्टॉल करें। इससे गलत निर्देश मिलने पर भी प्रभाव केवल उसी खाते तक सीमित रहेगा। यह सबसे महत्वपूर्ण निर्णय है।
• प्रोडक्शन क्रेडेंशियल्स को सर्वर पर न रखें। कोई prod ~/.aws/credentials न रखें, प्रोडक्शन से कोई .env कॉपी न करें, और न ही ऐसा डेटाबेस पासवर्ड रखें जिसे किसी महत्वपूर्ण चीज़ पर write एक्सेस हो। इसे केवल स्टेजिंग या read-only क्रेडेंशियल दें।
• इन-बिल्ट सैंडबॉक्स का उपयोग करें। Docker या Podman इंस्टॉल होने पर, gemini --sandbox (या GEMINI_SANDBOX=docker) एजेंट के टूल कॉल्स को एक ऐसे कंटेनर के अंदर चलाता है जो केवल वर्तमान प्रोजेक्ट डायरेक्टरी को माउंट करता है, न कि पूरे होस्ट फाइलसिस्टम को। यह अनप्रिविलेज्ड उपयोगकर्ता का विकल्प नहीं है, लेकिन जब एक ही VPS पर वास्तविक काम हो रहा हो, तो यह सुरक्षा की एक मजबूत दूसरी परत है।

यदि आप Gemini CLI को अन्य self-hosted टूल्स के साथ चला रहे हैं, जैसे कि एक MCP सर्वर जो उसी VPS पर एजेंट को टूल्स प्रदान करता है, तो प्रत्येक जोड़ी गई क्षमता को एजेंट की पहुँच का विस्तार मानें, और उसे दिए गए टोकन को केवल एक विशिष्ट कार्य तक ही सीमित रखें।

Quota, लागत, और आपके द्वारा चुना गया auth path

Auth path यह तय करता है कि आपसे शुल्क कैसे लिया जाएगा, और 18 जून, 2026 से यह भी तय होता है कि आपको सेवा मिलेगी या नहीं। Google की घोषणा के अनुसार, उस तारीख से Gemini CLI ने Google AI Pro और Ultra सब्सक्राइबर्स के लिए, और उन सभी के लिए अनुरोधों को प्रोसेस करना बंद कर दिया है जो इसे मुफ्त में इस्तेमाल कर रहे थे, जिसमें पर्सनल-अकाउंट फ्री टियर और बिना बिलिंग वाले API keys शामिल हैं। यह सेवा अब केवल सशुल्क Gemini API keys और Gemini Enterprise Agent Platform API keys के माध्यम से उपलब्ध है, जो प्रति टोकन शुल्क लेते हैं। इसके अलावा, जिन संगठनों के पास Gemini Code Assist Standard या Enterprise लाइसेंस है या जिन्हें Google Cloud का अन्य एक्सेस प्राप्त है, वे Google Cloud के माध्यम से बिलिंग करते हैं। प्रत्येक टियर में अभी भी प्रति-मिनट और प्रति-दिन की सीमाएं हैं; यदि आप इन्हें पार करते हैं, तो विंडो रीसेट होने तक अनुरोधों पर rate-limit error आएगा।

दो व्यावहारिक बातें ध्यान रखें। एक unattended agent लूप में बहुत तेजी से कोटा खत्म कर सकता है, इसलिए इसे cron job पर भरोसा करने से पहले पहली कुछ बार मॉनिटर करें। और यदि सर्वर-साइड मॉडल का उपयोग करने का आपका कारण गोपनीयता या unmetered inference है, न कि Google के होस्टेड मॉडल, तो यह एक अलग टूल का विषय है। Ollama के साथ VPS पर open LLM को self-host करना weights और prompts को आपके अपने सर्वर पर रखता है, लेकिन इसकी कीमत यह है कि आप Gemini की तुलना में काफी छोटा मॉडल चला पाएंगे।

इसे अपडेट रखना

Gemini CLI के नए versions अक्सर आते रहते हैं। चूंकि आपने इसे user-owned prefix में install किया है, इसलिए updates के लिए कभी भी sudo की आवश्यकता नहीं होती है:

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

इसके अलग-अलग release channels हैं: @latest stable version है, @preview weekly preview है, और @nightly bleeding edge version है। जिन applications पर आप निर्भर हैं, उनके लिए @latest को ही pin करें। nvm पर, global packages सक्रिय Node version के अंतर्गत रहते हैं, इसलिए Node switch करने के लिए nvm use चलाने के बाद आपको CLI को फिर से install करना पड़ सकता है। हर छोटे patch के पीछे भागने के बजाय release notes पढ़ें।

विफलता के प्रकार (Failure modes) और सटीक स्ट्रिंग्स

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, और उसके बाद रनटाइम पर CLI का क्रैश होना। Node का वर्ज़न बहुत पुराना है, डिस्ट्रो का 18.19.1 वर्ज़न अब end-of-life हो चुका है। NodeSource या nvm से वर्तमान LTS वर्ज़न इंस्टॉल करें (Node 20 CLI की न्यूनतम आवश्यकता को पूरा करता है, लेकिन यह भी अप्रैल 2026 से end-of-life हो चुका है), node --version के साथ पुष्टि करें, और यदि आपके पास कई Node वर्ज़न इंस्टॉल हैं, तो जाँचें कि which node नए वर्ज़न को पॉइंट कर रहा है, न कि /usr/bin/node को।

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'। रूट-ओन्ड प्रीफिक्स में ग्लोबल इंस्टॉलेशन। इसे 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://127.0.0.1:PORT को पॉइंट कर रहा है जिस तक आप नहीं पहुँच सकते। CLI को एक डिस्प्ले वेरिएबल मिला (अक्सर ssh -X से) और उसने लूपबैक फ्लो ले लिया, जिसका कॉलबैक सर्वर पर लैंड करता है। पेस्ट-ए-कोड फ्लो प्राप्त करने के लिए NO_BROWSER=true gemini चलाएं, या API-key पाथ (GEMINI_API_KEY) का उपयोग करें। एक सामान्य SSH सेशन पर आपको इसके बजाय Enter the authorization code: देखना चाहिए; अपने लैपटॉप ब्राउज़र में URL को अप्रूव करें और Google द्वारा दिखाए गए कोड को पेस्ट करें।

SSH डिस्कनेक्ट होने पर प्रोसेस गायब हो गई। आपने gemini को सीधे SSH शेल से चलाया, इसलिए यह उस शेल की चाइल्ड प्रोसेस थी और डिस्कनेक्ट होने पर pty के साथ समाप्त हो गई। इसे रिकवर नहीं किया जा सकता। हर सेशन की शुरुआत tmux new -A -s gemini से करें और CLI को उसके अंदर चलाएं।

की (key) सेट होने के बावजूद ऑथेंटिकेशन विफल रहता है, CLI वापस अपने ऑथ पिकर पर आ जाता है, या कोई रिक्वेस्ट HTTP 400 के साथ API key not valid लौटाती है। की उस एनवायरनमेंट में नहीं है जिसे CLI देख पा रहा है। printenv GEMINI_API_KEY के साथ पुष्टि करें; यदि यह खाली है, तो आपका ~/.gemini_env कभी सोर्स नहीं हुआ था, जाँचें कि यह लाइन ~/.bashrc में है या नहीं, जिसे इंटरैक्टिव शेल (tmux सहित) पढ़ते हैं लेकिन cron और अन्य नॉन-इंटरैक्टिव शेल नहीं पढ़ते। की वैल्यू के अंदर एक अतिरिक्त स्पेस या कोट भी API key not valid उत्पन्न करता है।

429 / RESOURCE_EXHAUSTED / रेट-लिमिट संदेश। आप उस टियर के लिए कोटा पार कर चुके हैं जिसका आपका ऑथ उपयोग करता है। विंडो के रीसेट होने का इंतज़ार करें, एजेंट की गति धीमी करें, या बिल किए गए API की (billed API key) पर स्विच करें। एक एजेंट जो रीट्राय लूप में फंसा है, वह बार-बार इसे हिट करता रहेगा, उसे रोकें और जाँचें कि वह क्या कर रहा है।

FAQ

Headless सर्वर पर Gemini CLI को authenticate कैसे करें?

Browser login के बजाय paid API key का उपयोग करें। Google AI Studio में एक billed project के अंतर्गत key बनाएँ, इसे mode-600 वाली एक ऐसी file में रखें जिसे आपका shell source करता हो (export GEMINI_API_KEY=...), इससे CLI पूरी तरह से OAuth browser flow को छोड़ देगा। यदि आप इसके बजाय Google से sign in करते हैं, उदाहरण के लिए Code Assist Standard या Enterprise licence पर, तो headless box पर CLI एक URL print करेगा; उसे अपने laptop पर खोलें, approve करें, और Google द्वारा दिखाए गए code को Enter the authorization code: prompt पर paste करें। इसमें कोई port pin करने या tunnel की आवश्यकता नहीं होती है, लेकिन इसके लिए आपका browser के सामने उपस्थित होना जरूरी है, इसलिए यह scripts के लिए उपयुक्त नहीं है। 18 जून, 2026 से Gemini CLI द्वारा free personal accounts को support नहीं दिया जा रहा है।

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 (npm config set prefix ~/.npm-global) की ओर point करें और इसके bin को PATH में जोड़ें, या nvm का उपयोग करें, जो global packages को स्वचालित रूप से आपके home के अंतर्गत install करता है।

disconnect होने के बाद मैं Gemini CLI को कैसे चालू रखूँ?

इसे tmux के अंदर चलाएँ। आपके SSH shell से शुरू की गई process connection drop होने पर समाप्त हो जाती है क्योंकि वह उस 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 के रूप में कुछ भी कर सकता है जिसके रूप में वह चलता है। इसे बिना sudo वाले एक dedicated unprivileged user के रूप में चलाएँ, production credentials को machine से दूर रखें, --yolo auto-approval से बचें, और host से tool calls को isolate करने के लिए --sandbox (Docker या Podman) का उपयोग करें। यह जिस account के अंतर्गत चलता है, वह आपके द्वारा set किए गए किसी भी एक flag से अधिक मायने रखता है।

क्या मुझे Gemini CLI के लिए कोई firewall port खोलने की आवश्यकता है?

नहीं। यह एक client है जो Google के APIs को outbound HTTPS calls करता है, इसलिए इसे outbound port 443 की आवश्यकता होती है लेकिन किसी inbound port की नहीं। Headless box पर Google sign-in के लिए भी किसी port की आवश्यकता नहीं होती है: आप सर्वर पर callback प्राप्त करने के बजाय terminal में एक code paste करते हैं। Inbound traffic को locked down रखें।