Install Gemini CLI In Headless Linux

HongHong
3 min read

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.

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!

0
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 :-)