Install Gemini CLI In Headless Linux


Tired of leaving your terminal for AI tasks? Gemini CLI is an open-source AI agent that brings the power of Google's Gemini directly to your command line. It's a fantastic alternative to tools like Claude Code, offering a seamless AI experience right where you work.
While Gemini CLI typically defaults to a browser-based login, this can be problematic for headless Linux environments (servers or systems without a graphical user interface). Thankfully, there's a straightforward way to authenticate using a Gemini API key, making it perfect for your GUI-less setup.
Setting Up Gemini CLI with an API Key
Here's how to get Gemini CLI up and running on your headless Linux machine:
1. Create Your Gemini API Key
The first step is to generate an API key for authentication.
- Navigate to Google AI Studio and create your API key: https://aistudio.google.com/apikey
Once you have your API key, you need to make it accessible to Gemini CLI. Add the following line to your shell's configuration file (either ~/.bashrc
for Bash or ~/.zshrc
for Zsh):
export GEMINI_API_KEY=<YOUR_API_KEY_HERE>
Important: Replace <YOUR_API_KEY_HERE>
with the actual API key you just generated. After adding the line, remember to source the file to apply the changes to your current terminal session. You can do this by running:
source ~/.bashrc
# OR
source ~/.zshrc
2. Install Gemini CLI
Before installing, ensure you have Node.js version 20 or higher installed on your system. If you don't, you'll need to install it first.
Once Node.js is ready, install Gemini CLI globally using npm:
sudo npm install -g @google/gemini-cli
3. Launch Gemini CLI and Authenticate
Now you're ready to launch Gemini CLI! Simply execute the gemini
command in your terminal:
gemini
During the initial launch, you'll be prompted to choose a theme and an authentication method. Crucially, select "Use Gemini API Key". Gemini CLI will automatically detect the GEMINI_API_KEY
environment variable you set, allowing for seamless authentication without a browser.
Troubleshooting Authentication Issues
Encountering problems during authentication? Here are a couple of common solutions:
Verify Your API Key: Double-check that your API key is correctly set as an environment variable by running:
echo $GEMINI_API_KEY
This command should display your API key. If it's empty or incorrect, re-verify the steps in the "Create Your Gemini API Key" section.
Clear Previous Session Data: If you've previously attempted to launch Gemini CLI and encountered authentication failures, there might be leftover configuration files causing issues. Delete the
~/.gemini
folder to clear these settings and then try launching Gemini CLI again:rm -rf ~/.gemini
After deleting the folder, run
gemini
again and select the "Use Gemini API Key" authentication method.
With these steps, you should have Gemini CLI running smoothly on your headless Linux system, ready to bring powerful AI capabilities directly to your command line.
Have you tried using Gemini CLI in a headless environment before? Share your experience in the comments below!
Subscribe to my newsletter
Read articles from Hong directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by

Hong
Hong
I am a developer from Malaysia. I work with PHP most of the time, recently I fell in love with Go. When I am not working, I will be ballroom dancing :-)