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.

Example	Feature	Run
`simple_query`	One-shot query	`cargo run --example simple_query`
`streaming`	Streaming responses	`cargo run --example streaming`
`multi_turn`	Multi-turn session	`cargo run --example multi_turn`
`with_permissions`	Tool approvals	`cargo run --example with_permissions`
`with_hooks`	Lifecycle hooks	`cargo run --example with_hooks`

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.