Add OpenRouter integration and custom CLI name feature

OPENROUTER_INTEGRATION_SUMMARY.md

@@ -0,0 +1,149 @@
+# OpenRouter Integration Summary
+
+This document summarizes the changes made to add OpenRouter support to the Gemini CLI as an alternative API provider.
+
+## Overview
+
+The integration allows users to use OpenRouter's unified API instead of Google's servers to access Gemini and other AI models. The CLI automatically detects which API to use based on available credentials.
+
+## Files Modified
+
+### Core Changes
+
+1. **`packages/core/src/core/contentGenerator.ts`**
+   - Added `AuthType.USE_OPENROUTER` enum value
+   - Updated `ContentGeneratorConfig` interface to include `openRouterBaseUrl`
+   - Modified `createContentGeneratorConfig()` to handle OpenRouter environment variables
+   - Updated `createContentGenerator()` to instantiate OpenRouter client when appropriate
+
+2. **`packages/core/src/core/openRouterContentGenerator.ts`** (NEW FILE)
+   - Complete OpenRouter API client implementation
+   - Converts between Gemini API format and OpenAI-compatible format used by OpenRouter
+   - Implements all required methods: `generateContent`, `generateContentStream`, `countTokens`, `embedContent`
+   - Handles function calling, system instructions, and generation parameters
+   - Provides proper type conversions and error handling
+
+3. **`packages/core/src/core/auth.ts`**
+   - Added `OPENROUTER_API_KEY` environment variable validation
+   - Updated authentication logic to support OpenRouter
+
+### CLI Changes
+
+4. **`packages/cli/src/gemini.tsx`**
+   - Added automatic fallback logic to detect and use OpenRouter when API key is available
+   - Maintains backward compatibility with existing Google API authentication
+
+5. **`packages/cli/src/config/config.ts`**
+   - Added CLI arguments: `--openrouter-api-key` and `--openrouter-base-url`
+   - Added help text for OpenRouter options
+
+6. **`packages/cli/src/config/settings.ts`**
+   - Added `OpenRouterSettings` interface
+   - Updated main `Settings` interface to include OpenRouter configuration
+
+### Documentation
+
+7. **`docs/openrouter.md`** (NEW FILE)
+   - Comprehensive guide for OpenRouter setup and usage
+   - Examples, troubleshooting, and feature compatibility information
+
+8. **`README.md`**
+   - Added section about OpenRouter as alternative API provider
+   - Quick setup instructions with link to detailed guide
+
+## Key Features
+
+### Automatic Detection
+- CLI automatically detects which API to use based on available credentials
+- Priority: OpenRouter API key → Google API key → Google Cloud credentials
+
+### Full API Compatibility
+- ✅ Text generation
+- ✅ Streaming responses  
+- ✅ Function calling (where supported by model)
+- ✅ System instructions
+- ✅ Temperature and generation parameters
+- ✅ Token counting (estimated)
+- ❌ Embedding (not supported by OpenRouter's unified API)
+
+### Configuration Options
+- Environment variable: `OPENROUTER_API_KEY`
+- CLI arguments: `--openrouter-api-key`, `--openrouter-base-url`
+- Custom base URL support for alternative endpoints
+
+### Model Support
+- Any model available on OpenRouter can be used
+- Examples: `google/gemini-pro`, `anthropic/claude-3-sonnet`, `openai/gpt-4`
+
+## Usage Examples
+
+### Basic Usage
+```bash
+export OPENROUTER_API_KEY="your-api-key"
+gemini --prompt "Hello, world!"
+```
+
+### With Specific Model
+```bash
+gemini --openrouter-api-key "your-key" --model "google/gemini-2.0-flash" --prompt "Explain AI"
+```
+
+### Interactive Mode
+```bash
+export OPENROUTER_API_KEY="your-api-key"
+gemini  # Starts interactive session
+```
+
+## Technical Implementation
+
+### Type Safety
+- Full TypeScript support with proper type conversions
+- Maintains compatibility with existing `@google/genai` types
+- Handles union types for content, parts, and function calls
+
+### API Translation
+- Converts Gemini API requests to OpenAI-compatible format
+- Translates responses back to Gemini API format
+- Preserves all metadata including token usage and function calls
+
+### Error Handling
+- Proper error propagation from OpenRouter API
+- Maintains existing error handling patterns
+- Clear error messages for authentication and API issues
+
+### Streaming Support
+- Full streaming response support using async generators
+- Maintains real-time response display in CLI
+- Proper cleanup and error handling for streams
+
+## Testing
+
+The integration has been tested with:
+- ✅ Build system (TypeScript compilation)
+- ✅ CLI argument parsing
+- ✅ Automatic API detection
+- ✅ Error handling with invalid credentials
+- ✅ Help text display
+
+## Benefits
+
+1. **Alternative Access**: Provides alternative when Google's API is unavailable
+2. **Model Variety**: Access to multiple AI providers through single interface
+3. **Cost Management**: Potentially better pricing through OpenRouter
+4. **Global Access**: May work in regions where Google's API is restricted
+5. **Unified Interface**: Single CLI for multiple AI providers
+
+## Backward Compatibility
+
+- All existing functionality remains unchanged
+- Existing Google API authentication continues to work
+- No breaking changes to CLI interface
+- Graceful fallback when OpenRouter credentials are not available
+
+## Future Enhancements
+
+Potential future improvements:
+- Support for OpenRouter's embedding models when available
+- Model-specific feature detection
+- Enhanced error messages with OpenRouter-specific guidance
+- Configuration file support for OpenRouter settings

README.md

@@ -51,6 +51,21 @@ If you need to use a specific model or require a higher request capacity, you ca
 
 For other authentication methods, including Google Workspace accounts, see the [authentication](./docs/cli/authentication.md) guide.
 
+### Alternative API Provider: OpenRouter
+
+The Gemini CLI also supports [OpenRouter](https://openrouter.ai/) as an alternative API provider, which provides access to multiple AI models through a unified interface:
+
+1. Get an API key from [OpenRouter](https://openrouter.ai/)
+2. Set it as an environment variable:
+
+   ```bash
+   export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
+   ```
+
+3. Use the CLI normally - it will automatically detect and use OpenRouter
+
+For detailed OpenRouter setup and usage instructions, see the [OpenRouter integration guide](./docs/openrouter.md).
+
 ## Examples
 
 Once the CLI is running, you can start interacting with Gemini from your shell.

docs/openrouter.md

@@ -0,0 +1,181 @@
+# OpenRouter Integration
+
+The Gemini CLI now supports using OpenRouter as an alternative API provider to Google's servers. OpenRouter provides a unified API for accessing various AI models, including Gemini models, through a single interface.
+
+## Setup
+
+### 1. Get an OpenRouter API Key
+
+1. Visit [OpenRouter](https://openrouter.ai/)
+2. Sign up for an account
+3. Generate an API key from your dashboard
+
+### 2. Configure the CLI
+
+You can configure OpenRouter in several ways:
+
+#### Environment Variables
+
+Set the `OPENROUTER_API_KEY` environment variable:
+
+```bash
+export OPENROUTER_API_KEY="your-openrouter-api-key-here"
+```
+
+#### Command Line Arguments
+
+Use the CLI arguments directly:
+
+```bash
+gemini --openrouter-api-key "your-api-key" --prompt "Hello, world!"
+```
+
+#### Custom Base URL
+
+If you need to use a different OpenRouter endpoint:
+
+```bash
+gemini --openrouter-api-key "your-api-key" --openrouter-base-url "https://custom-endpoint.com/api/v1" --prompt "Hello!"
+```
+
+## Usage
+
+### Basic Usage
+
+Once configured, the CLI will automatically detect and use OpenRouter when an API key is available:
+
+```bash
+# Set the environment variable
+export OPENROUTER_API_KEY="your-api-key"
+
+# Use the CLI normally
+gemini --prompt "Explain quantum computing"
+```
+
+### Model Selection
+
+You can use any model available on OpenRouter by specifying it with the `--model` flag:
+
+```bash
+# Use Google's Gemini Pro via OpenRouter
+gemini --model "google/gemini-pro" --prompt "Hello!"
+
+# Use other models available on OpenRouter
+gemini --model "anthropic/claude-3-sonnet" --prompt "Hello!"
+gemini --model "openai/gpt-4" --prompt "Hello!"
+```
+
+### Interactive Mode
+
+OpenRouter works seamlessly with the interactive mode:
+
+```bash
+export OPENROUTER_API_KEY="your-api-key"
+gemini  # Starts interactive mode using OpenRouter
+```
+
+## API Compatibility
+
+The OpenRouter integration maintains full compatibility with the Gemini CLI's existing features:
+
+- ✅ Text generation
+- ✅ Streaming responses
+- ✅ Function calling (where supported by the model)
+- ✅ System instructions
+- ✅ Temperature and other generation parameters
+- ✅ Token counting (estimated)
+- ❌ Embedding (not supported by OpenRouter's unified API)
+
+## Fallback Behavior
+
+The CLI automatically detects which API to use based on available credentials:
+
+1. **OpenRouter**: If `OPENROUTER_API_KEY` is set or `--openrouter-api-key` is provided
+2. **Google API**: If `GEMINI_API_KEY` is set or Google Cloud credentials are available
+3. **Error**: If no valid credentials are found
+
+## Configuration Priority
+
+When multiple configuration methods are used, the priority is:
+
+1. Command line arguments (`--openrouter-api-key`, `--openrouter-base-url`)
+2. Environment variables (`OPENROUTER_API_KEY`)
+3. Default values
+
+## Examples
+
+### Simple Text Generation
+
+```bash
+export OPENROUTER_API_KEY="your-api-key"
+gemini --prompt "Write a haiku about programming"
+```
+
+### Using a Specific Model
+
+```bash
+gemini --openrouter-api-key "your-key" --model "google/gemini-2.0-flash" --prompt "Explain machine learning"
+```
+
+### Interactive Session
+
+```bash
+export OPENROUTER_API_KEY="your-api-key"
+gemini
+# Now you can chat interactively using OpenRouter
+```
+
+### Custom Temperature
+
+```bash
+gemini --openrouter-api-key "your-key" --model "google/gemini-pro" --prompt "Be creative: write a story" --temperature 0.9
+```
+
+## Troubleshooting
+
+### Authentication Errors
+
+If you see authentication errors:
+
+1. Verify your API key is correct
+2. Check that your OpenRouter account has sufficient credits
+3. Ensure the API key has the necessary permissions
+
+### Model Not Found
+
+If you get model not found errors:
+
+1. Check the model name is correct (use the format `provider/model-name`)
+2. Verify the model is available on OpenRouter
+3. Ensure your account has access to the specific model
+
+### Rate Limiting
+
+OpenRouter has its own rate limits. If you encounter rate limiting:
+
+1. Check your OpenRouter dashboard for current limits
+2. Consider upgrading your OpenRouter plan
+3. Implement delays between requests if needed
+
+## Benefits of Using OpenRouter
+
+1. **Unified API**: Access multiple AI providers through a single interface
+2. **Cost Management**: Potentially better pricing and credit management
+3. **Model Variety**: Access to models from multiple providers
+4. **Reliability**: Alternative access path if Google's API is unavailable
+5. **Global Access**: May provide better access in regions where Google's API is restricted
+
+## Limitations
+
+1. **Embedding**: OpenRouter doesn't support embedding endpoints, so embedding features will not work
+2. **Model-Specific Features**: Some Gemini-specific features may not be available through OpenRouter
+3. **Latency**: Additional network hop may introduce slight latency
+4. **Feature Parity**: Not all OpenRouter models support all features (like function calling)
+
+## Support
+
+For issues specific to OpenRouter integration:
+
+1. Check the [OpenRouter documentation](https://openrouter.ai/docs)
+2. Verify your API key and account status
+3. Report bugs to the Gemini CLI repository with the `openrouter` label

packages/cli/src/config/auth.ts

@@ -35,5 +35,12 @@ export const validateAuthMethod = (authMethod: string): string | null => {
     return null;
   }
 
+  if (authMethod === AuthType.USE_OPENROUTER) {
+    if (!process.env.OPENROUTER_API_KEY) {
+      return 'OPENROUTER_API_KEY environment variable not found. Add that to your .env and try again, no reload needed!';
+    }
+    return null;
+  }
+
   return 'Invalid auth method selected.';
 };