Using OneAster with Gemini CLI

Introduction

Gemini CLI is Google’s official command-line tool that lets developers interact with Gemini AI models from the terminal. After configuring OneAster API, you can use OneAster’s advanced models—GPT, Claude, and Gemini—in Gemini CLI.

Prerequisites

Before you start:

Node.js and npm installed
Download and install from the Node.js website (v16 or higher recommended)
OneAster API key
Sign in to the OneAster Console and copy your API key (starts with sk-)

Tip: If you don’t have an OneAster account yet, register at OneAster first and create an API key.

Step 1: Install Gemini CLI

1.1 Global install

Install Gemini CLI globally with npm:

npm install -g @google/gemini-cli

1.2 Verify installation

Check that the CLI is available:

gemini --version

If a version number is printed, installation succeeded.

Tip: If the command is not found, restart your terminal or check your npm global PATH configuration.

Step 2: Configure OneAster API

2.1 Temporary environment variables

For testing or one-off use; values are cleared when you close the terminal. Windows (PowerShell):

$env:GEMINI_API_KEY = "sk-xxxxxxxxxxxx"
$env:GEMINI_BASE_URL = "https://api.oneaster.ai/v1"

macOS/Linux (Bash):

export GEMINI_API_KEY="sk-xxxxxxxxxxxx"
export GEMINI_BASE_URL="https://api.oneaster.ai/v1"

2.2 Permanent environment variables (recommended)

Persist configuration so new shells pick it up automatically. Windows (PowerShell):

Run PowerShell as Administrator
Set user-level environment variables:

[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'sk-xxxxxxxxxxxx', 'User')
[System.Environment]::SetEnvironmentVariable('GEMINI_BASE_URL', 'https://api.oneaster.ai/v1', 'User')

Restart PowerShell, or reload variables:

$env:GEMINI_API_KEY = [System.Environment]::GetEnvironmentVariable('GEMINI_API_KEY', 'User')
$env:GEMINI_BASE_URL = [System.Environment]::GetEnvironmentVariable('GEMINI_BASE_URL', 'User')

macOS/Linux (Bash):

Edit your shell rc file:

# Bash
nano ~/.bashrc

# Zsh (default on macOS)
nano ~/.zshrc

Append:

# oneaster Gemini CLI
export GEMINI_API_KEY="sk-xxxxxxxxxxxx"
export GEMINI_BASE_URL="https://api.oneaster.ai/v1"

Reload:

source ~/.bashrc   # Bash
source ~/.zshrc    # Zsh

2.3 Using a `.env` file

Create .env in your project:

# .env
GEMINI_API_KEY=sk-xxxxxxxxxxxx
GEMINI_BASE_URL=https://api.oneaster.ai/v1

Load variables before running Gemini: macOS/Linux:

export $(cat .env | xargs) && gemini chat

Windows (PowerShell):

Get-Content .env | ForEach-Object {
    $name, $value = $_.split('=')
    Set-Content env:\$name $value
}
gemini chat

Important: - Replace sk-xxxxxxxxxxxx with your real key from the OneAster Console - Set GEMINI_BASE_URL to https://api.oneaster.ai/v1 so Gemini CLI talks to OneAster - Add .env to .gitignore so keys are not committed

2.4 Verify configuration

macOS/Linux:

echo $GEMINI_API_KEY
echo $GEMINI_BASE_URL

Windows (PowerShell):

echo $env:GEMINI_API_KEY
echo $env:GEMINI_BASE_URL

If the values look correct, configuration succeeded.

Step 3: Use Gemini CLI

3.1 Basic chat

Interactive session:

gemini chat

One-off prompt:

gemini "Give a short overview of the history of artificial intelligence"

3.2 Choose a model

gemini chat --model gpt-4o

Or:

gemini "Write a Python quicksort implementation" --model claude-sonnet-4-5-20250929

3.3 Read prompts from a file

gemini --input prompt.txt

Or pipe:

cat prompt.txt | gemini

3.4 Save output to a file

gemini "Generate a React component" --output component.jsx

Step 4: Call OneAster from your code

4.1 Python SDK

import openai

# oneaster
openai.api_key = "sk-xxxxxxxxxxxx"  # Your oneaster API key
openai.api_base = "https://api.oneaster.ai/v1"

response = openai.ChatCompletion.create(
    model="gemini-2.0-flash-exp",
    messages=[
        {"role": "user", "content": "Hi—please introduce yourself"}
    ]
)

print(response.choices[0].message.content)

4.2 JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxxxxxxxxx",
  baseURL: "https://api.oneaster.ai/v1",
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "gemini-2.0-flash-exp",
    messages: [{ role: "user", content: "Hi—please introduce yourself" }],
  });

  console.log(completion.choices[0].message.content);
}

main();

4.3 cURL

curl https://api.oneaster.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -d '{
    "model": "gemini-2.0-flash-exp",
    "messages": [
      {"role": "user", "content": "Hi—please introduce yourself"}
    ]
  }'

Step 5: Pick a model

Recommended models

OneAster supports many models; choose by task and budget. Gemini

Model name	Model ID	Characteristics	Good for
Gemini 2.0 Flash	`gemini-2.0-flash-exp`	Fast, multimodal	Quick answers, vision + text
Gemini 2.5 Pro	`gemini-2.5-pro`	Strong capability	Hard problems, analysis
Gemini 2.5 Flash	`gemini-2.5-flash`	Very responsive	Real-time chat, batch jobs

GPT

Model name	Model ID	Characteristics	Good for
GPT-5	`gpt-5`	Top-tier	Reasoning, creative writing
GPT-4o	`gpt-4o`	High quality	General chat, content
GPT-4o Mini	`gpt-4o-mini`	Cost-efficient	Simple tasks, high volume

Claude

Model name	Model ID	Characteristics	Good for
Claude Sonnet 4.5	`claude-sonnet-4-5-20250929`	Strong reasoning	Code, logic
Claude Haiku 4.5	`claude-haiku-4-5-20251001`	Very fast	Q&A, low-latency chat

Quick picks: - 🚀 Google-style stack: gemini-2.0-flash-exp, gemini-2.5-pro - 💡 Coding: claude-sonnet-4-5-20250929, gpt-5 - 💰 Cost: gpt-4o-mini, claude-haiku-4-5-20251001 - ⚡ Speed: gemini-2.0-flash-exp, gpt-4o-mini

Advanced features

Multimodal (images)

With a multimodal model such as Gemini 2.0 Flash:

response = openai.ChatCompletion.create(
    model="gemini-2.0-flash-exp",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What’s in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    }
                }
            ]
        }
    ]
)

Streaming

Stream tokens as they arrive:

stream = openai.ChatCompletion.create(
    model="gemini-2.0-flash-exp",
    messages=[{"role": "user", "content": "Write a short poem about spring"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end='')

Tuning parameters

Shape randomness and length:

response = openai.ChatCompletion.create(
    model="gemini-2.0-flash-exp",
    messages=[{"role": "user", "content": "Your question"}],
    temperature=0.7,        # randomness (0–2)
    max_tokens=2000,        # max output length
    top_p=0.9,              # nucleus sampling
    presence_penalty=0,     # topic diversity
    frequency_penalty=0     # repetition penalty
)

FAQ

Q1: “Invalid API key” or auth errors

Key format
- Must start with sk-
- No extra spaces when pasting

Environment variables

# macOS / Linux
echo $GEMINI_API_KEY
echo $GEMINI_BASE_URL

# Windows PowerShell
echo $env:GEMINI_API_KEY
echo $env:GEMINI_BASE_URL

Key status
- Check the key in the OneAster Console
- Ensure your account has balance

Q2: How do I verify the API setup?

import openai

openai.api_key = "sk-xxxxxxxxxxxx"
openai.api_base = "https://api.oneaster.ai/v1"

try:
    response = openai.ChatCompletion.create(
        model="gemini-2.0-flash-exp",
        messages=[{"role": "user", "content": "test"}],
        max_tokens=10
    )
    print("✅ API configuration OK")
    print(f"Reply: {response.choices[0].message.content}")
except Exception as e:
    print(f"❌ API configuration failed: {e}")

Q3: Which languages are supported?

Any language that can send HTTP requests works with OneAster:

✅ Python — OpenAI SDK recommended
✅ JavaScript / TypeScript — Node or browser
✅ Java — HTTP client
✅ Go — stdlib or libraries
✅ PHP — cURL or Guzzle
✅ Ruby — HTTP gems
✅ C# / .NET — HttpClient
✅ Swift — URLSession
✅ Others — anything with HTTP

Q4: Where can I see usage and billing?

In the OneAster Console:

📊 Live call stats
💰 Cost and invoices
📈 Usage trends
🔍 Request logs
⚙️ API key management

Q5: Common API errors

Error	Likely cause	What to do
`401 Unauthorized`	Bad or revoked key	Fix key in env / console
`429 Too Many Requests`	Rate limit	Slow down or upgrade plan
`500 Internal Server Error`	Transient server issue	Retry later; contact support if it persists
`insufficient_quota`	Low balance	Top up in console

Best practices

1. Retries and backoff

import openai
import time

def call_with_retry(max_retries=3):
    for i in range(max_retries):
        try:
            response = openai.ChatCompletion.create(
                model="gemini-2.0-flash-exp",
                messages=[{"role": "user", "content": "Your question"}]
            )
            return response
        except openai.error.RateLimitError:
            if i < max_retries - 1:
                time.sleep(2 ** i)
                continue
            raise
        except Exception as e:
            print(f"Error: {e}")
            raise

response = call_with_retry()

2. Cost control

def choose_model(complexity):
    if complexity == "simple":
        return "gpt-4o-mini"
    elif complexity == "medium":
        return "gemini-2.0-flash-exp"
    return "gpt-5"

model = choose_model("simple")
response = openai.ChatCompletion.create(
    model=model,
    messages=[{"role": "user", "content": "Your question"}],
    max_tokens=500
)

3. System prompts

response = openai.ChatCompletion.create(
    model="gemini-2.0-flash-exp",
    messages=[
        {
            "role": "system",
            "content": "You are an expert Python assistant who writes clear, efficient code."
        },
        {
            "role": "user",
            "content": "Implement quicksort for me"
        }
    ]
)

Features

With Google AI Studio and OneAster you get:

🤖 Many models — GPT, Claude, Gemini, and more
🌍 OpenAI-compatible — familiar request / response shape
⚡ Performance — low latency, high concurrency
💰 Clear pricing — pay as you go
📊 Observability — monitor calls in real time
🔒 Security — enterprise-oriented safeguards
🚀 Fast integration — simple HTTP / SDK calls
📚 Docs — guides and examples

Support

Get started with OneAster

Create an account, grab an API key, and use multiple AI models from Google AI Studio workflows and beyond.

​Introduction

​Prerequisites

​Step 1: Install Gemini CLI

​1.1 Global install

​1.2 Verify installation

​Step 2: Configure OneAster API

​2.1 Temporary environment variables

​2.2 Permanent environment variables (recommended)

​2.3 Using a .env file

​2.4 Verify configuration

​Step 3: Use Gemini CLI

​3.1 Basic chat

​3.2 Choose a model

​3.3 Read prompts from a file

​3.4 Save output to a file

​Step 4: Call OneAster from your code

​4.1 Python SDK

​4.2 JavaScript / TypeScript

​4.3 cURL

​Step 5: Pick a model

​Recommended models

​Advanced features

​Multimodal (images)

​Streaming

​Tuning parameters

​FAQ

​Q1: “Invalid API key” or auth errors

​Q2: How do I verify the API setup?

​Q3: Which languages are supported?

​Q4: Where can I see usage and billing?

​Q5: Common API errors

​Best practices

​1. Retries and backoff

​2. Cost control

​3. System prompts

​Features

​Support

Get started with OneAster

Introduction

Prerequisites

Step 1: Install Gemini CLI

1.1 Global install

1.2 Verify installation

Step 2: Configure OneAster API

2.1 Temporary environment variables

2.2 Permanent environment variables (recommended)

2.3 Using a `.env` file

2.4 Verify configuration

Step 3: Use Gemini CLI

3.1 Basic chat

3.2 Choose a model

3.3 Read prompts from a file

3.4 Save output to a file

Step 4: Call OneAster from your code

4.1 Python SDK

4.2 JavaScript / TypeScript

4.3 cURL

Step 5: Pick a model

Recommended models

Advanced features

Multimodal (images)

Streaming

Tuning parameters

FAQ

Q1: “Invalid API key” or auth errors

Q2: How do I verify the API setup?

Q3: Which languages are supported?

Q4: Where can I see usage and billing?

Q5: Common API errors

Best practices

1. Retries and backoff

2. Cost control

3. System prompts

Features

Support