hasina-gemini-cli 1.0.0

package/.env.example

@@ -0,0 +1,4 @@
+GEMINI_API_KEY=your_gemini_api_key_here
+DEFAULT_MODEL=gemini-2.5-flash
+MAX_HISTORY_MESSAGES=20
+SYSTEM_PROMPT=You are a helpful terminal AI assistant focused on clear, accurate, and practical answers.

package/README.md

@@ -0,0 +1,334 @@
+# Gemini CLI
+
+Gemini CLI is a production-ready terminal chat application for Node.js that uses the official `@google/genai` SDK. It provides a polished CLI, streaming-friendly architecture, local JSON session storage, bounded conversation context, and a clean service-based structure that can grow into a multi-provider AI client later.
+
+## Features
+
+- Interactive terminal chat loop
+- Official Gemini API integration through `@google/genai`
+- Runtime model switching with `/use-model`
+- Numbered model chooser with `/models`
+- Session-level system prompt support
+- Bounded context memory for provider requests
+- Local JSON session persistence in `data/sessions.json`
+- Slash command system for session and runtime controls
+- Streaming-ready chat architecture with Gemini streaming enabled
+- Friendly, actionable terminal errors
+- Cross-platform support for Windows, macOS, and Linux
+
+## Folder Structure
+
+```text
+Gemini-Cli/
+  src/
+    config/
+      env.js
+      gemini.js
+    services/
+      chat.service.js
+      history.service.js
+      session.service.js
+      command.service.js
+    utils/
+      printer.js
+      file.js
+      validators.js
+    app.js
+    index.js
+  data/
+    sessions.json
+  .env.example
+  package.json
+  README.md
+```
+
+## Installation
+
+### Prerequisites
+
+- Node.js 20 or later
+- A Gemini API key from Google AI Studio
+
+Note: the original product brief said Node.js 18+, but the current official `@google/genai` package requires Node.js 20+ as of March 10, 2026.
+
+### Quick install from GitHub
+
+Install globally:
+
+```bash
+npm install -g github:Hasina69/Gemini-Cli
+```
+
+Run:
+
+```bash
+gemini-cli
+```
+
+### Install from npm after publishing
+
+Once the package is published on npm, install globally with:
+
+```bash
+npm install -g hasina-gemini-cli
+```
+
+Or run it directly without a global install:
+
+```bash
+npx hasina-gemini-cli
+```
+
+### Local development install
+
+Clone and install:
+
+```bash
+git clone https://github.com/Hasina69/Gemini-Cli.git
+cd Gemini-Cli
+npm install
+```
+
+Then create your environment file.
+
+### Environment file setup
+
+For local repo usage, create `.env` in the project root.
+
+Windows PowerShell:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+macOS/Linux:
+
+```bash
+cp .env.example .env
+```
+
+For global install usage, create `.env` in one of these locations:
+
+- Current working directory: `.env`
+- Windows shared config: `%APPDATA%\GeminiCli\.env`
+- macOS shared config: `~/Library/Application Support/GeminiCli/.env`
+- Linux shared config: `~/.gemini-cli/.env`
+
+Update that `.env` with your Gemini API key and preferred defaults.
+
+## How To Create `GEMINI_API_KEY` In Google AI Studio
+
+1. Open [Google AI Studio](https://aistudio.google.com/apikey).
+2. Sign in with your Google account.
+3. Create a new API key.
+4. Copy the generated key.
+5. Paste it into your local `.env` file as `GEMINI_API_KEY`.
+
+## Environment Configuration
+
+Use these variables in `.env`:
+
+```env
+GEMINI_API_KEY=your_gemini_api_key_here
+DEFAULT_MODEL=gemini-2.5-flash
+MAX_HISTORY_MESSAGES=20
+SYSTEM_PROMPT=You are a helpful terminal AI assistant focused on clear, accurate, and practical answers.
+```
+
+### Variable Notes
+
+- `GEMINI_API_KEY`: required for authenticating to Gemini
+- `DEFAULT_MODEL`: the model loaded at startup
+- `MAX_HISTORY_MESSAGES`: max number of recent messages sent back to Gemini as context
+- `SYSTEM_PROMPT`: default system instruction for each new session
+- `GEMINI_CLI_HOME`: optional custom config directory for shared `.env` and session storage
+- `GEMINI_CLI_SESSIONS_FILE`: optional custom path for `sessions.json`
+
+## Running The App
+
+If you used the global install:
+
+```bash
+gemini-cli
+```
+
+If you are running from the local repo:
+
+Development mode:
+
+```bash
+npm run dev
+```
+
+Production mode:
+
+```bash
+npm start
+```
+
+## Command Reference
+
+| Command | Description |
+| --- | --- |
+| `/help` | Show all commands |
+| `/exit` | Exit the app cleanly |
+| `/clear` | Clear in-memory history for the current session |
+| `/history` | Show recent conversation messages |
+| `/models` | Open a numbered Gemini model chooser |
+| `/save` | Persist the current session to local session storage |
+| `/new` | Start a fresh conversation session |
+| `/model` | Show the currently active model |
+| `/use-model <model_name>` | Switch the active Gemini model at runtime |
+| `/system` | Show the active system prompt |
+| `/set-system <text>` | Override the current system prompt for this session |
+| `/sessions` | List saved local sessions |
+| `/load <session_id>` | Load a saved session from local storage |
+
+## Example Terminal Session
+
+```text
+GEMINI CLI banner...
+
+Info > Active model: gemini-2.5-flash
+Info > Session ID: session_001
+Info > Type a message to chat, use /models to choose a model, or /help to list commands.
+
+You > /models
+Command > Choose a Gemini Model
+01. gemini-2.5-flash [active]
+    Gemini 2.5 Flash | input 1M | output 65.5K
+02. gemini-2.5-pro
+    Gemini 2.5 Pro | input 1M | output 65.5K
+Model > 2
+Success > Active model changed to "gemini-2.5-pro".
+
+You > Explain event loops in Node.js.
+Gemini > The Node.js event loop coordinates timers, I/O callbacks, microtasks,
+         and application work without blocking the main thread...
+
+You > /save
+Success > Session "session_001" saved to local session storage.
+
+You > /exit
+Info > Closing Gemini Terminal.
+```
+
+## Architecture Notes
+
+- `src/config/gemini.js` contains the Gemini-specific provider wrapper
+- `src/services/chat.service.js` is provider-oriented and keeps request building separate from the terminal UI
+- `src/services/history.service.js` stores provider-neutral messages using `{ role, content }`
+- `src/services/session.service.js` isolates local JSON persistence
+- `src/services/command.service.js` parses commands without depending on terminal rendering
+- `src/utils/printer.js` owns terminal presentation and loading behavior
+
+This makes it straightforward to add future providers such as OpenAI or Claude without rewriting the app loop.
+
+## Notes About Changing Models
+
+- The startup model comes from `DEFAULT_MODEL` in `.env`
+- Use `/model` to inspect the active model
+- Use `/models` to open a numbered chooser and switch without typing the full model name
+- Use `/use-model gemini-2.5-flash` or another valid Gemini model name to switch at runtime
+- `/use-model` validates the model with the Gemini API before applying the change
+- If a saved session is loaded with `/load`, the saved model becomes the active model
+
+## Notes About Local Session Storage
+
+- Local repo mode stores sessions in `data/sessions.json`
+- Global install mode stores sessions in your shared config directory:
+  - Windows: `%APPDATA%\GeminiCli\sessions.json`
+  - macOS: `~/Library/Application Support/GeminiCli/sessions.json`
+  - Linux: `~/.gemini-cli/sessions.json`
+- The app does not auto-save on exit; use `/save` when you want persistence
+- Each saved session stores:
+  - session ID
+  - creation and update timestamps
+  - active model
+- active system prompt
+- provider-neutral messages
+- If `data/sessions.json` becomes malformed JSON, the app will stop with a clear storage error instead of silently overwriting data
+
+## One-Line Commands
+
+Global install from GitHub:
+
+```bash
+npm install -g github:Hasina69/Gemini-Cli
+```
+
+Global install from npm after publishing:
+
+```bash
+npm install -g hasina-gemini-cli
+```
+
+Run with npx after publishing:
+
+```bash
+npx hasina-gemini-cli
+```
+
+Run after global install:
+
+```bash
+gemini-cli
+```
+
+Local clone and run:
+
+```bash
+git clone https://github.com/Hasina69/Gemini-Cli.git
+cd Gemini-Cli
+npm install
+npm start
+```
+
+## Troubleshooting
+
+### Missing `GEMINI_API_KEY`
+
+If startup fails with a configuration error, confirm `.env` exists and includes a non-empty `GEMINI_API_KEY`.
+
+### Invalid Or Unsupported Model
+
+If Gemini rejects a model:
+
+- verify the name with `/use-model`
+- try a known working model such as `gemini-2.5-flash`
+- confirm your API key has access to that model
+
+### Rate Limits Or Quota Errors
+
+If you see rate limit or quota messages:
+
+- wait and retry later for rate limiting
+- check quota and billing in Google AI Studio for quota exhaustion
+
+### Node Version Errors
+
+If `npm install` or startup fails on Node 18 or Node 19:
+
+- upgrade to Node 20+
+- reinstall dependencies after upgrading
+
+### Broken Session Storage
+
+If the session storage file is manually edited and becomes invalid JSON:
+
+- fix the JSON manually
+- or replace it with:
+
+  ```json
+  {
+    "sessions": []
+  }
+  ```
+
+### Network Failures
+
+If Gemini requests fail due to connectivity:
+
+- check your internet connection
+- retry after transient failures
+- verify corporate firewall or proxy rules are not blocking outbound HTTPS requests

package/bin/gemini-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../src/index');

package/data/sessions.json

@@ -0,0 +1,3 @@
+{
+  "sessions": []
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "hasina-gemini-cli",
+  "version": "1.0.0",
+  "description": "Production-ready terminal AI chat application powered by the official Gemini API SDK.",
+  "main": "src/index.js",
+  "bin": {
+    "gemini-cli": "bin/gemini-cli.js"
+  },
+  "files": [
+    "bin",
+    "data",
+    "src",
+    "README.md",
+    ".env.example"
+  ],
+  "type": "commonjs",
+  "preferGlobal": true,
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "nodemon src/index.js",
+    "start": "node src/index.js"
+  },
+  "keywords": [
+    "gemini",
+    "terminal",
+    "cli",
+    "ai",
+    "chat"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hasina69/Gemini-Cli.git"
+  },
+  "homepage": "https://github.com/Hasina69/Gemini-Cli",
+  "bugs": {
+    "url": "https://github.com/Hasina69/Gemini-Cli/issues"
+  },
+  "dependencies": {
+    "@google/genai": "^1.44.0",
+    "chalk": "^4.1.2",
+    "dotenv": "^16.4.7",
+    "figlet": "^1.11.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.10"
+  }
+}

package/src/app.js

@@ -0,0 +1,285 @@
+const readline = require('readline/promises');
+const { stdin: input, stdout: output } = require('process');
+const { ChatService } = require('./services/chat.service');
+const { CommandService } = require('./services/command.service');
+const { HistoryService } = require('./services/history.service');
+const { SessionService } = require('./services/session.service');
+
+function normalizeAssistantText(text) {
+  if (typeof text !== 'string') {
+    return '';
+  }
+
+  return text.trim();
+}
+
+class App {
+  constructor({ config, provider, printer }) {
+    this.config = config;
+    this.provider = provider;
+    this.printer = printer;
+    this.readline = null;
+    this.isShuttingDown = false;
+
+    this.historyService = new HistoryService({
+      maxMessages: config.maxHistoryMessages,
+    });
+
+    this.sessionService = new SessionService({
+      storagePath: config.sessionsFilePath,
+    });
+
+    this.chatService = new ChatService({
+      provider,
+      maxHistoryMessages: config.maxHistoryMessages,
+    });
+
+    this.commandService = new CommandService({
+      sessionService: this.sessionService,
+      provider,
+    });
+
+    this.state = null;
+  }
+
+  async initializeState() {
+    await this.sessionService.ensureStorage();
+
+    this.state = {
+      sessionId: await this.sessionService.generateSessionId(),
+      sessionCreatedAt: new Date().toISOString(),
+      model: this.config.defaultModel,
+      systemPrompt: this.config.systemPrompt,
+      historyService: this.historyService,
+    };
+  }
+
+  async printStartup() {
+    await this.printer.printBanner({
+      animated: process.stdout.isTTY && process.env.GEMINI_CLI_BANNER_ANIMATION === '1',
+    });
+    this.printer.printInfo(`Active model: ${this.state.model}`);
+    this.printer.printInfo(`Session ID: ${this.state.sessionId}`);
+    this.printer.printInfo('Type a message to chat, use /models to choose a model, or /help to list commands.');
+  }
+
+  async start() {
+    await this.initializeState();
+    await this.printStartup();
+
+    this.readline = readline.createInterface({
+      input,
+      output,
+      terminal: true,
+      historySize: 1000,
+    });
+
+    this.readline.on('SIGINT', () => {
+      this.isShuttingDown = true;
+      this.printer.printInfo('Received Ctrl+C. Exiting cleanly.');
+      this.readline.close();
+    });
+
+    try {
+      while (!this.isShuttingDown) {
+        let rawInput = '';
+
+        try {
+          rawInput = await this.readline.question(this.printer.getUserPrompt());
+        } catch (error) {
+          if (this.isShuttingDown || this.isReadlineClosedError(error)) {
+            break;
+          }
+
+          throw error;
+        }
+
+        const userInput = rawInput.trim();
+
+        if (!userInput) {
+          continue;
+        }
+
+        if (this.commandService.isCommand(userInput)) {
+          const commandResult = await this.commandService.execute(userInput, this.state);
+          const shouldExit = await this.handleCommandResult(commandResult);
+
+          if (shouldExit) {
+            break;
+          }
+
+          continue;
+        }
+
+        await this.handleChatTurn(userInput);
+      }
+    } finally {
+      await this.shutdown();
+    }
+  }
+
+  async handleCommandResult(result) {
+    if (!result) {
+      return false;
+    }
+
+    if (result.kind === 'block') {
+      this.printer.printCommandBlock(result.title, result.lines);
+      return Boolean(result.exit);
+    }
+
+    if (result.kind === 'model-picker') {
+      return this.handleModelPicker(result);
+    }
+
+    if (result.level === 'success') {
+      this.printer.printSuccess(result.message);
+      return Boolean(result.exit);
+    }
+
+    if (result.level === 'error') {
+      this.printer.printError(result.message);
+      return Boolean(result.exit);
+    }
+
+    this.printer.printInfo(result.message);
+    return Boolean(result.exit);
+  }
+
+  async handleModelPicker(result) {
+    this.printer.printCommandBlock(result.title, result.lines);
+    let answer = '';
+
+    try {
+      answer = await this.readline.question('Model > ');
+    } catch (error) {
+      if (this.isShuttingDown || this.isReadlineClosedError(error)) {
+        return true;
+      }
+
+      throw error;
+    }
+
+    const selection = answer.trim();
+
+    if (!selection) {
+      this.printer.printInfo('Model selection cancelled.');
+      return false;
+    }
+
+    const selectedModel = this.resolveModelSelection(selection, result.models);
+
+    if (!selectedModel) {
+      this.printer.printError(
+        'Invalid model selection. Use /models and choose a listed number or model name.'
+      );
+      return false;
+    }
+
+    if (selectedModel.id === this.state.model) {
+      this.printer.printInfo(`"${selectedModel.id}" is already the active model.`);
+      return false;
+    }
+
+    this.state.model = selectedModel.id;
+    this.printer.printSuccess(`Active model changed to "${selectedModel.id}".`);
+    return false;
+  }
+
+  resolveModelSelection(selection, models) {
+    if (!Array.isArray(models) || models.length === 0) {
+      return null;
+    }
+
+    if (/^\d+$/.test(selection)) {
+      const index = Number.parseInt(selection, 10) - 1;
+      return models[index] || null;
+    }
+
+    const normalizedSelection = selection.replace(/^models\//i, '').toLowerCase();
+
+    return (
+      models.find((model) => model.id.toLowerCase() === normalizedSelection) ||
+      models.find((model) => model.displayName.toLowerCase() === normalizedSelection) ||
+      null
+    );
+  }
+
+  async handleChatTurn(userInput) {
+    const loading = this.printer.createLoadingIndicator();
+    let streamStarted = false;
+
+    loading.start();
+
+    try {
+      const result = await this.chatService.sendMessage({
+        model: this.state.model,
+        systemPrompt: this.state.systemPrompt,
+        historyMessages: this.state.historyService.getMessages(),
+        userMessage: userInput,
+        preferStreaming: true,
+        onTextChunk: (chunk) => {
+          if (!streamStarted) {
+            loading.stop();
+            this.printer.startAssistantStream();
+            streamStarted = true;
+          }
+
+          this.printer.writeAssistantChunk(chunk);
+        },
+      });
+
+      loading.stop();
+
+      const assistantText =
+        normalizeAssistantText(result.text) || 'No text response returned by Gemini.';
+
+      if (streamStarted) {
+        this.printer.endAssistantStream();
+
+        if (!normalizeAssistantText(result.text)) {
+          this.printer.printInfo('Gemini returned an empty text response.');
+        }
+      } else {
+        this.printer.printAssistant(assistantText);
+      }
+
+      this.state.historyService.addMessage('user', userInput);
+      this.state.historyService.addMessage('assistant', assistantText);
+    } catch (error) {
+      loading.stop();
+
+      if (streamStarted) {
+        this.printer.endAssistantStream();
+      }
+
+      this.printer.printError(error.message || 'Unexpected error while talking to Gemini.');
+    }
+  }
+
+  async shutdown() {
+    if (this.readline) {
+      try {
+        this.readline.close();
+      } catch (error) {
+        if (!this.isReadlineClosedError(error)) {
+          throw error;
+        }
+      } finally {
+        this.readline = null;
+      }
+    }
+  }
+
+  isReadlineClosedError(error) {
+    return (
+      error &&
+      (error.code === 'ERR_USE_AFTER_CLOSE' ||
+        /The "readline" interface is closed/i.test(error.message || ''))
+    );
+  }
+}
+
+module.exports = {
+  App,
+};