gemini-cli-headless 1.0.1

A resilient, zero-dependency Python wrapper for the official Google Gemini Node.js CLI.

gemini-cli-headless

A standalone, zero-dependency Python wrapper for executing the official Node.js Google Gemini CLI (@google/gemini-cli) in fully programmatic, headless mode.

Note: While gemini-cli-headless is a powerful standalone library, it also serves as the foundational execution engine for Cortex, an Autonomous Developer OS for multi-agent software engineering.

Why this wrapper?

While the official Python SDKs are excellent for standard API calls, the @google/gemini-cli provides powerful built-in features for developers working with local codebases (e.g., attaching entire directories via @files or resuming specific sessionId chat histories from the CLI's internal cache).

This wrapper allows you to leverage those CLI-specific features headlessly within your Python scripts, Data pipelines, or RAG systems. It is built for absolute resilience, featuring native retry loops for transient infrastructure drops.

Features

• Zero Dependencies: Pure Python standard library (no requests, no aiohttp).
• JSON Parsing: Automatically requests and safely parses the --output-format json from the Node CLI into a clean Python GeminiSession dataclass.
• Token & Cost Stats: Aggregates inputTokens, outputTokens, and cachedTokens from the raw JSON response.
• Session Resumption: Supports the -r <sessionId> flag, and even allows you to inject local .json session files directly into the Node CLI cache before execution.
• Built-in Resilience: Automatically catches transient API drops (like 503 errors) and malformed JSON, retrying the subprocess call seamlessly without crashing your script.

Installation

This wrapper requires the official Node.js CLI to be available on your system.

# 1. Install the official Node.js CLI globally (requires Node.js):
npm install -g @google/gemini-cli

# 2. Install the Python wrapper via PyPI:
pip install gemini-cli-headless

Quick Start

from gemini_cli_headless import run_gemini_cli_headless

# Provide your API key explicitly, or let the wrapper use your environment variables
my_key = "AIzaSy..."

# Execute a command headlessly with built-in retries
session = run_gemini_cli_headless(
    prompt="Explain quantum computing in one sentence.",
    api_key=my_key,
    max_retries=3
)

print(f"Cost basis - Input: {session.stats.get('inputTokens')}, Output: {session.stats.get('outputTokens')}")
print(f"Response: {session.text}")
print(f"Session ID: {session.session_id}")

Portable Memory (Resuming from a local file)

Instead of relying on the global CLI cache, you can keep session files directly in your project and inject them on the fly.

import shutil
from gemini_cli_headless import run_gemini_cli_headless

# 1. First interaction
session = run_gemini_cli_headless("Remember the secret password is 'Rosebud'.")

# 2. Save the session to your local project
shutil.copy2(session.session_path, "my_context.json")

# ... Days later on a different machine ...

# 3. Resume the conversation later from your local file!
new_session = run_gemini_cli_headless(
    prompt="What was the secret password?",
    session_to_resume="my_context.json"
)