gemini-cli-sdk

Strongly-typed, async-first Rust SDK for building agents on the Google Gemini CLI (gemini --experimental-acp).

Features

• One-shot queries - query() / query_with_content() return collected messages
• Streaming - query_stream() / query_stream_with_content() yield messages as they arrive
• Multi-turn sessions - Client with send() / send_content() for persistent threads
• Multimodal input - text + image URLs or base64 blobs via UserContent
• Permission callbacks - CanUseToolCallback for per-tool approval/denial
• Lifecycle hooks - HookMatcher for PreToolUse, PostToolUse, Stop, etc.
• MCP server config - attach Model Context Protocol servers at session start
• Message callbacks - observe or log messages without interrupting the stream
• Testing framework - MockTransport + ScenarioBuilder (feature testing)
• Cross-platform - macOS, Linux, and Windows

Quick Start

[dependencies]
gemini-cli-sdk = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use gemini_cli_sdk::query;

#[tokio::main]
async fn main() -> gemini_cli_sdk::Result<()> {
    let msgs = query("Summarize this repo").await?;
    for msg in msgs {
        if let Some(text) = msg.assistant_text() {
            println!("{text}");
        }
    }
    Ok(())
}

Examples

All examples require a working Gemini CLI installation and authentication.

Testing

Enable mock testing support:

gemini-cli-sdk = { version = "0.1", features = ["testing"] }

Run the test suites:

cargo test
cargo test --features testing
cargo test --features live-tests -- --nocapture

Disclaimer

This is an unofficial, community-developed SDK and is not affiliated with, endorsed by, or sponsored by Google. "Gemini" is a trademark of Google. This crate interacts with the Gemini CLI but does not contain any Google proprietary code.

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.

Maintained by the POM team.