> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini CLI

> Configure Google Gemini CLI to use TokenLab API

## Overview

<Note>
  **Type**: Coding Tool

  **Primary Path**: Gemini-native

  **Support Confidence**: Best-effort
</Note>

Google Gemini CLI is a command-line tool for interacting with Gemini models. TokenLab compatibility here is experimental: Gemini CLI officially documents Google-native authentication and settings, but does not currently document a stable custom TokenLab-style base URL workflow.

<Warning>
  Treat this integration as best-effort compatibility, not a guaranteed long-term setup. If you need a stable TokenLab terminal coding workflow, prefer Codex CLI, Claude Code, or OpenCode.
</Warning>

## System Requirements

* **Node.js**: Version 20.0+
* **OS**: Windows 10/11, macOS 10.15+, Ubuntu 20.04+, or Debian 10+

## Installation

```bash theme={null}
npm install -g @google/gemini-cli
```

Verify installation:

```bash theme={null}
gemini --version
```

## Configuration

### Step 1: Get Your API Key

1. Log into [TokenLab Dashboard](https://tokenlab.sh/dashboard)
2. Navigate to [API Keys](https://tokenlab.sh/dashboard/api)
3. Create and copy your API key (format: `sk-...`)

### Step 2: Set Environment Variables

The following setup is the current compatibility path people use with proxy or gateway endpoints, but it is not an official Gemini CLI integration:

**Temporary (current session):**

```bash theme={null}
export GEMINI_API_KEY="sk-your-tokenlab-key"
export GOOGLE_GEMINI_BASE_URL="https://api.tokenlab.sh"
```

**Permanent configuration:**

Add to your shell configuration file:

<Tabs>
  <Tab title="Bash">
    ```bash theme={null}
    echo 'export GEMINI_API_KEY="sk-your-tokenlab-key"' >> ~/.bashrc
    echo 'export GOOGLE_GEMINI_BASE_URL="https://api.tokenlab.sh"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="Zsh">
    ```bash theme={null}
    echo 'export GEMINI_API_KEY="sk-your-tokenlab-key"' >> ~/.zshrc
    echo 'export GOOGLE_GEMINI_BASE_URL="https://api.tokenlab.sh"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="Fish">
    ```bash theme={null}
    set -Ux GEMINI_API_KEY "sk-your-tokenlab-key"
    set -Ux GOOGLE_GEMINI_BASE_URL "https://api.tokenlab.sh"
    ```
  </Tab>
</Tabs>

<Warning>
  Restart your terminal after configuration for changes to take effect.
</Warning>

<Note>
  Known limitation: Gemini CLI may ignore `GOOGLE_GEMINI_BASE_URL` in some situations, especially when an existing Google login or cached auth flow takes precedence. If this happens, start a fresh terminal session, clear cached auth, or use another client.
</Note>

## Basic Usage

Start Gemini CLI from your project directory:

```bash theme={null}
cd your-project
gemini
```

On first run, you'll:

1. Choose a theme
2. Confirm safety notice
3. Trust the working directory

## Available Models

| Model                   | Description                      |
| ----------------------- | -------------------------------- |
| `gemini-2.5-pro`        | Most capable Gemini model        |
| `gemini-3.5-flash`      | Fast, efficient for most tasks   |
| `gemini-3.1-flash-lite` | Current lightweight Gemini model |

## Common Commands

**Ask a question:**

```
> What is the best way to structure a React app?
```

**Analyze code:**

```
> Explain the code in src/main.ts
```

**Generate code:**

```
> Create a Python function to parse JSON files
```

**Review changes:**

```
> Review the recent git changes and suggest improvements
```

## Verify Configuration

```bash theme={null}
# Check environment variables
echo $GEMINI_API_KEY
echo $GOOGLE_GEMINI_BASE_URL

# Test connection
gemini
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Error">
    * Verify `GOOGLE_GEMINI_BASE_URL` is set to `https://api.tokenlab.sh`
    * Note: Do not add `/v1` for this compatibility path
    * Check network connectivity
  </Accordion>

  <Accordion title="Authentication Failed">
    * Verify `GEMINI_API_KEY` environment variable is set
    * Check that the key starts with `sk-`
    * Ensure the key is active in TokenLab dashboard
  </Accordion>

  <Accordion title="Model Not Available">
    * Check Gemini models availability at [tokenlab.sh/en/models](https://tokenlab.sh/en/models)
    * Try a different Gemini model variant
  </Accordion>

  <Accordion title="Need a more stable coding workflow">
    * Gemini CLI's custom gateway compatibility can regress between releases
    * Prefer Codex CLI, Claude Code, or OpenCode if you need a documented TokenLab path
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Use in project directory">
    Always run Gemini CLI from your project root for better context understanding.
  </Accordion>

  <Accordion title="Trust directories carefully">
    Only trust directories you own. Gemini CLI can read and modify files.
  </Accordion>

  <Accordion title="Review generated code">
    Always review AI-generated code before committing to your project.
  </Accordion>
</AccordionGroup>