gemini-cli-sdk 0.1.0

Rust SDK wrapping Google's Gemini CLI as a subprocess via JSON-RPC 2.0
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# gemini-cli-sdk

[![Crates.io](https://img.shields.io/crates/v/gemini-cli-sdk.svg)](https://crates.io/crates/gemini-cli-sdk)
[![docs.rs](https://docs.rs/gemini-cli-sdk/badge.svg)](https://docs.rs/gemini-cli-sdk)
[![CI](https://github.com/pomdotdev/gemini-cli-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/pomdotdev/gemini-cli-sdk/actions/workflows/ci.yml)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](#license)

Strongly-typed, async-first Rust SDK for building agents on the [Google Gemini CLI](https://ai.google.dev/gemini-api/docs/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

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

```rust
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`](examples/simple_query.rs) | One-shot query | `cargo run --example simple_query` |
| [`streaming`](examples/streaming.rs) | Streaming responses | `cargo run --example streaming` |
| [`multi_turn`](examples/multi_turn.rs) | Multi-turn session | `cargo run --example multi_turn` |
| [`with_permissions`](examples/with_permissions.rs) | Tool approvals | `cargo run --example with_permissions` |
| [`with_hooks`](examples/with_hooks.rs) | Lifecycle hooks | `cargo run --example with_hooks` |

## Testing

Enable mock testing support:

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

Run the test suites:

```bash
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](LICENSE-APACHE) or [MIT License](LICENSE-MIT) at your option.

---

Maintained by the [POM](https://pom.dev) team.