Gemini-CLI: A Portable Command-Line Client for the Google Gemini API

Gemini-CLI is a powerful, portable, and feature-rich command-line client for the Google Gemini API. It provides a fluid, shell-like interface for conversing with large language models, designed for developers, writers, and power-users who live in the terminal.

It is written in C for maximum performance and portability, with no dependencies beyond standard system libraries and a few common open-source projects.

Features

• Deep Mode (/deep, /deeper): An innovative, multi-step prompting technique to elicit higher-quality, more refined responses. The client silently orchestrates a multi-turn conversation where the model iteratively critiques and improves its own answers, finally synthesizing them into a single, optimal response.
• Key-Free Mode: Use the client without an API key via the -f flag. The client automatically falls back to this mode if no API key is provided, making it instantly usable.
• Multi-Key Management:
  • Automatic Rotation: Store and rotate through multiple API keys to manage rate limits and improve reliability.
  • Full Management Suite: Add, list, remove, and validate keys directly from the command line (--add-key, --list-keys, etc.) or an interactive session (/keys ...).
• Dual-Mode Operation: Functions as both a fully featured interactive chat client and a non-interactive, scriptable command-line tool. The mode is automatically detected based on whether input is being piped to the program.
• Advanced Scripting & Piping:
  • Pipe content directly (cat file | gemini-cli "summarize this").
  • Use a hyphen (-) to treat standard input as an attachment (git diff | gemini-cli "commit message for: -").
  • Quiet Mode (-q): Suppresses all informational output, printing only the final model response to stdout.
  • Execute Mode (-e): Forces a non-interactive run for a single prompt, even if not using pipes.
  • Save the history of a non-interactive run with --save-session.
• Robust and Reliable:
  • Automatic Retries: Automatically retries API requests up to 3 times on 503 Service Unavailable errors.
  • Proxy Support: Route all API requests through a specified HTTP/S proxy with the -p flag.
• Streaming Responses: In interactive mode, see the model's response generated in real-time, just like in web UIs.
• File & URL Attachments:
  • Attach images, source code, PDFs, and other files to your prompts (/attach).

Getting Started

1. Clone the Repository

First, get the source code using git:

git clone https://github.com/Zibri/gemini-cli.git
cd gemini-cli

2. Install Prerequisites

You will need a C compiler (gcc or clang) and the development headers for the following libraries:

• cURL: For making HTTP requests.
• zlib: For Gzip compression.
• readline (POSIX only): For advanced line editing and persistent history.

On Debian/Ubuntu:

sudo apt-get update
sudo apt-get install build-essential libcurl4-openssl-dev libreadline-dev zlib1g-dev

On openSUSE/Tumbleweed:

sudo zypper refresh
sudo zypper install gcc make libcurl-devel readline-devel zlib-devel

On Fedora/CentOS/RHEL:

sudo dnf install gcc make curl-devel readline-devel zlib-devel

On macOS (using Homebrew):

brew install curl readline zlib
# You may need to provide linker flags if they aren't found automatically

On Windows:

The easiest way to build on Windows is by using a POSIX-like environment such as MSYS2.

1. After installing MSYS2, open the MSYS2 CLANG64 terminal from your Start Menu.

2. Inside the terminal, use pacman to update the system and install the required compiler and development libraries with this single command:

   pacman -Suy libcurl-devel libreadline-devel clang make
   

3. Once the installation is complete, you can compile the program by simply running:

   make
   

3. Compile the Program

The project includes a Makefile that automatically detects your operating system and compiles the program with the correct settings. Simply run:```bash make

This will create an executable named `gemini-cli` (or `gemini-cli.exe` on Windows). You can move this file to a directory in your system's `PATH` (e.g., `/usr/local/bin` or `~/bin`) for easy access.

### 4. Configuration
There are two ways to use the client: with an API key (official API) or without one (unofficial API).

1.  **Key-Free Mode (Easiest Start):**
    Simply run the client with the `-f` or `--free` flag. If no API key is found from other sources, the client will **automatically fall back** to this mode.
    ```bash
    ./gemini-cli -f "Hello, world!"
    ```

2.  **Using an API Key (Official API):**
    To use the official Google Gemini API, you need to provide your API key. You can get one from [Google AI Studio](https://aistudio.google.com/app/apikey). The client loads the key in the following order of priority:

    *   **Environment Variable (Highest Priority):**
        Set the `GEMINI_API_KEY` environment variable.
        ```bash
        export GEMINI_API_KEY="your_api_key_here"
        ```
        **For Restricted Keys (Optional):**
        If you have secured your API key to an HTTP referrer, set the `GEMINI_API_KEY_ORIGIN` environment variable. This sends the required `Origin` HTTP header.
        ```bash
        export GEMINI_API_KEY_ORIGIN="https://my-app.com"
        ```

    *   **Configuration File:**
        The client will look for a `config.json` file. You can create this file to set a default model, temperature, API keys, or system prompt.
        *   **POSIX:** `~/.config/gemini-cli/config.json`
        *   **Windows:** `%APPDATA%\gemini-cli\config.json`

        *Example `config.json`:*
        ```json
        {
          "api_keys": [
            "your_first_api_key",
            "your_second_api_key"
          ],
          "origins": [
            "https://your-allowed-origin.com",
            "default"
          ],
          "model": "gemini-2.5-pro",
          "proxy": "http://localhost:8080",
          "temperature": 0.75,
          "seed": 42,
          "system_prompt": "You are a helpful and concise assistant.",
          "google_grounding": true,
          "url_context": true,
          "max_output_tokens": 8192,
          "top_k": 40,
          "top_p": 0.95
        }
        ```

    *   **Interactive Prompt (Last Resort):**
        If no key is found and you do not use the `-f` flag, the program will securely prompt you to enter it when it first runs in interactive mode.

## Usage

### Command-Line Arguments
You can control the model and generation parameters at startup using these flags. Any other arguments are treated as an initial prompt or file attachments.

| Flag | Alias | Description | Example |
|---|---|---|---|
| `--help` | `-h` | Show the help message and exit. | `./gemini-cli --help` |
| `--free` | `-f` | Use the unofficial, key-free API endpoint. | `./gemini-cli -f` |
| `--execute` | `-e` | Force non-interactive mode for a single prompt. | `gemini-cli -e "What is 2+2?"` |
| `--quiet` | `-q` | Suppress banners and info for clean scripting output. | `cat file.c | ./gemini-cli -q "summarize"` |
| `--config <path>` | `-c` | Load configuration from a specific file path. | `./gemini-cli -c /path/to/myconfig.json` |
| `--model <name>` | `-m` | Specify the model name to use. | `./gemini-cli -m gemini-2.5-pro` |
| `--proxy <url>` | `-p` | Use a proxy for API requests. | `./gemini-cli -p http://localhost:8080` |
| `--system <prompt>` | `-S` | Set a system prompt for the entire session. | `./gemini-cli -S "You are a C code expert."` |
| `--temp <float>` | `-t` | Set the generation temperature (e.g., 0.0 to 2.0). | `./gemini-cli -t 0.25` |
| `--seed <int>` | `-s` | Set the generation seed for reproducible outputs. | `./gemini-cli -s 1234` |
| `--max-tokens <int>` | `-o` | Set the maximum number of tokens in the response. | `./gemini-cli -o 2048` |
| `--budget <int>` | `-b` | Set the model's max 'thinking' token budget. | `./gemini-cli -b 8192` |
| `--topk <int>` | | Set the Top-K sampling parameter. | `./gemini-cli --topk 40` |
| `--topp <float>` | | Set the Top-P sampling parameter. | `./gemini-cli --topp 0.95` |
| `--no-grounding` | `-ng` | Disable Google Search grounding. | `./gemini-cli -ng` |
| `--no-url-context` | `-nu` | Disable URL context processing. | `./gemini-cli -nu` |
| `--list` | `-l` | List all available models and exit. | `./gemini-cli -l` |
| `--list-sessions` | | List all saved sessions and exit. | `./gemini-cli --list-sessions` |
| `--load-session <name>`| | Load a saved session by name. | `./gemini-cli --load-session my_chat` |
| `--save-session <file>`| | Save conversation from a non-interactive run. | `cat f.c | gemini-cli "prompt" --save-session f.json` |
| `--list-keys` | | List API keys from the configuration file and exit. | `./gemini-cli --list-keys` |
| `--add-key` | | Add a new API key to the configuration file and exit. | `./gemini-cli --add-key` |
| `--remove-key <index>` | | Remove an API key from the configuration file and exit. | `./gemini-cli --remove-key 1` |
| `--check-keys` | | Validate all configured API keys and exit. | `./gemini-cli --check-keys` |
| `--loc` | | Get location information (requires `--free` mode). | `./gemini-cli -f --loc` |
| `--map` | | Get map URL for location (requires `--free` mode). | `./gemini-cli -f --map` |

### Interactive Mode
To start a conversation, simply run the executable. T