GeminiCliSdk

Hex.pm VersionHexDocsLicenseDownloads

GeminiCliSdk

An Elixir SDK for the Gemini CLI -- build AI-powered applications with Google Gemini through a robust, idiomatic wrapper around the Gemini command-line interface.

Documentation Menu

Features

Installation

Add gemini_cli_sdk to your dependencies in mix.exs:

def deps do
  [
    {:gemini_cli_sdk, "~> 0.2.0"}
  ]
end

Prerequisites: The Gemini CLI must be installed and authenticated.

Quick Start

Streaming

GeminiCliSdk.execute("Explain GenServer in 3 sentences")
|> Enum.each(fn event ->
  case event do
    %GeminiCliSdk.Types.MessageEvent{role: "assistant", content: text} ->
      IO.write(text)
    _ ->
      :ok
  end
end)

Synchronous

{:ok, response} = GeminiCliSdk.run("What is Elixir?")
IO.puts(response)

With Options

opts = %GeminiCliSdk.Options{
  model: GeminiCliSdk.Models.fast_model(),
  yolo: true,
  timeout_ms: 60_000
}

{:ok, response} = GeminiCliSdk.run("Refactor this function", opts)

Sessions

# List sessions
{:ok, sessions} = GeminiCliSdk.list_sessions()

# Resume a session
GeminiCliSdk.resume_session("abc123", %GeminiCliSdk.Options{}, "Continue")
|> Enum.each(fn event ->
  case event do
    %GeminiCliSdk.Types.MessageEvent{role: "assistant", content: text} ->
      IO.write(text)
    _ -> :ok
  end
end)

Event Types

Struct Description
Types.InitEvent Session initialized with session_id and model
Types.MessageEvent Message chunk with role and content
Types.ToolUseEvent Tool invocation with tool_name and parameters
Types.ToolResultEvent Tool result with tool_id and output
Types.ErrorEvent Error with severity and message
Types.ResultEvent Final result with status and stats

All stream-event structs are now schema-backed. Known fields are normalized through Zoi, forward-compatible unknown fields are preserved in extra, and the event modules expose to_map/1 for projection back to wire shape.

Architecture

GeminiCliSdk preserves its public API while running the common CLI session lane on cli_subprocess_core.

The current layering is:

GeminiCliSdk public API
  -> GeminiCliSdk.Stream / GeminiCliSdk.Runtime.CLI
  -> CliSubprocessCore.Session
  -> CliSubprocessCore raw transport
  -> gemini CLI

GeminiCliSdk command helpers
  -> CliSubprocessCore.Command.run/2
  -> CliSubprocessCore raw transport
  -> gemini CLI

GeminiCliSdk.Runtime.CLI is the Gemini runtime kit. It starts core sessions, preserves Gemini CLI command resolution and option shaping, and projects normalized core events back into GeminiCliSdk.Types.*.

The preserved GeminiCliSdk.Transport modules are public Gemini entrypoints backed by the core raw transport layer instead of owning a separate subprocess runtime.

Ownership Boundary

The final Phase 4 boundary for Gemini is:

Public Gemini entrypoints stay the same:

Gemini CLI resolution, option shaping, and public result/error mapping remain in this repo above the shared core.

No separate Gemini-owned common subprocess runtime remains here. Repo-local ownership is limited to Gemini CLI discovery, argument and environment shaping, typed event/result projection, and the public Gemini transport surface above the shared core.

The release and composition model is:

If gemini_cli_sdk is installed alongside agent_session_manager, ASM reports Gemini runtime availability in ASM.Extensions.ProviderSDK.capability_report/0 but keeps namespaces: [] because Gemini currently composes through the common ASM surface only.

Centralized Model Selection

gemini_cli_sdk now consumes model payloads resolved by cli_subprocess_core. The SDK no longer owns active fallback/defaulting policy for provider selection.

Authoritative policy surface:

Gemini-side responsibility is limited to:

No repo-local Gemini model fallback remains.

GeminiCliSdk.Options.validate!/1 canonicalizes explicit payloads through the shared core boundary. A CliSubprocessCore.ModelRegistry.Selection is the preferred form, and Map.from_struct(selection) is normalized back into the same canonical payload when callers already have a serialized struct map.

Documentation

Full documentation is available at HexDocs.

Examples

See the examples/ directory for live examples that run against the real Gemini CLI:

mix run examples/simple_prompt.exs
mix run examples/streaming.exs
bash examples/run_all.sh

License

MIT License. See LICENSE for details.

Model Selection Contract

See Centralized Model Selection. The Gemini SDK renders provider transport args from the shared resolved payload and does not emit nil/null/blank model values.

Session Listing And Resume Surfaces

Gemini now exposes a typed session-history projection for orchestration layers that need to recover an existing CLI conversation instead of replaying prompts from scratch.

The runtime also now carries system_prompt through the validated options surface so the caller can resume with the same instruction context it started with.