gemini-cli-headless 2.0.0

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

Gemini CLI Headless

⚠️ CRITICAL: VERSION LOCK This orchestrator relies on deeply undocumented internal mechanics of the policy engine. It is strictly version-locked and certified ONLY for Gemini CLI v0.38.2. Using newer versions may cause the sandbox to silently fail. See Version Lock & System Brittleness for details.

gemini-cli-headless is a Python-based Headless Orchestrator for the Gemini CLI. It provides a secure, programmatically controllable execution environment designed for autonomous agents, automated workflows, and complex system integrations (such as Cortex OS).

This wrapper moves beyond simple convenience flags and establishes a 100% physically secure, "Zero-Trust" sandbox by directly manipulating the internal policy engine of the Gemini CLI.

Quick Start

import os
from gemini_cli_headless import run_gemini_cli_headless

project_root = os.path.abspath("./my_project")

session = run_gemini_cli_headless(
    prompt="Refactor the authentication logic.",
    cwd=project_root,
    # 1. Physical Tool Sandbox
    allowed_tools=["read_file", "replace", "run_shell_command"],
    # 2. Physical Path Sandbox
    allowed_paths=[project_root], 
    # 3. Surgical Shell Sandbox
    allowed_commands=["npm test", "git status"] 
)

print(session.text)

Documentation

The architecture and security philosophy of this orchestrator are deeply intertwined with the internal physics of the Gemini CLI. To understand how to leverage it effectively, please refer to the detailed documentation:

• 01. Architecture Overview - The "Cognition vs. Enforcement" philosophy.
• 02. The Tier System & Priority Caps - Why we use the --admin-policy (Tier 5) Kernel.
• 03. Path Security & Structural Anchoring - Defeating content-injection using Null Bytes (\0).
• 04. Soft Interception & Model Psychology - Using "Invisible Enforcement" to overcome model paranoia.
• 05. Trace Auditing & Testing Philosophy - Why we test the physical engine traces, not the model's text.
• 06. Usage & Examples - Detailed API usage and common sandbox configurations.
• 07. Version Lock & System Brittleness - [IMPORTANT] Why the system is locked to v0.38.2 and the likely breaking points in future updates.

Running the Integrity Battery

To verify the physical security of the engine on your machine, you can run the exhaustive 29-point test battery.

python tests/run_integrity.py <optional_model_id> <optional_regex_filter>

Example (Run only path security tests):

python tests/run_integrity.py gemini-3-flash-preview "sec_paths"