GeminiCliSdk (gemini_cli_sdk v0.2.0)

An Elixir SDK for the Gemini CLI.

Provides streaming and synchronous execution of Gemini CLI prompts, session management, and typed event parsing.

Streaming

GeminiCliSdk.execute("Explain OTP", %GeminiCliSdk.Options{model: GeminiCliSdk.Models.fast_model()})
|> 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?")

Session Management

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

GeminiCliSdk.resume_session("latest")
|> Enum.each(&IO.inspect/1)

Summary

Functions

delete_session(identifier, opts \\ [])

Deletes a session by index or ID.

execute(prompt, opts \\ %Options{})

Starts a Gemini CLI session and returns a lazy stream of typed events.

list_session_entries(opts \\ [])

See GeminiCliSdk.Session.list_entries/1.

list_sessions(opts \\ [])

Lists available sessions for the current project.

resume_session(session_id, opts \\ %Options{}, prompt \\ nil)

Resumes a previous session and returns a streaming event enumerable.

run(prompt, opts \\ %Options{})

Executes a prompt and blocks until the CLI produces a final result.

version()

Returns the installed Gemini CLI version string.

Types

event()

@type event() :: GeminiCliSdk.Types.stream_event()

Functions

delete_session(identifier, opts \\ [])

@spec delete_session(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, GeminiCliSdk.Error.t()}

Deletes a session by index or ID.

execute(prompt, opts \\ %Options{})

@spec execute(String.t(), GeminiCliSdk.Options.t()) :: Enumerable.t(event())

Starts a Gemini CLI session and returns a lazy stream of typed events.

The stream is backed by Stream.resource/3. It spawns the gemini subprocess with --output-format stream-json and --prompt carrying the prompt text, then yields one event struct per JSONL line. The subprocess is killed and cleaned up when the stream is halted, fully consumed, or the owning process dies.

list_session_entries(opts \\ [])

@spec list_session_entries(keyword()) ::
  {:ok, [GeminiCliSdk.Session.Entry.t()]} | {:error, GeminiCliSdk.Error.t()}

See GeminiCliSdk.Session.list_entries/1.

list_sessions(opts \\ [])

@spec list_sessions(keyword()) :: {:ok, String.t()} | {:error, GeminiCliSdk.Error.t()}

Lists available sessions for the current project.

Runs gemini --list-sessions and returns the raw output.

resume_session(session_id, opts \\ %Options{}, prompt \\ nil)

@spec resume_session(String.t(), GeminiCliSdk.Options.t(), String.t() | nil) ::
  Enumerable.t(event())

Resumes a previous session and returns a streaming event enumerable.

run(prompt, opts \\ %Options{})

@spec run(String.t(), GeminiCliSdk.Options.t()) ::
  {:ok, String.t()} | {:error, GeminiCliSdk.Error.t()}

Executes a prompt and blocks until the CLI produces a final result.

Internally calls execute/2 and reduces the stream, collecting assistant message text. Returns {:ok, response_text} on success or {:error, %Error{}} on any failure.

version()

@spec version() :: {:ok, String.t()} | {:error, GeminiCliSdk.Error.t()}

Returns the installed Gemini CLI version string.