# `GeminiCliSdk`
[🔗](https://github.com/nshkrdotcom/gemini_cli_sdk/blob/v0.2.0/lib/gemini_cli_sdk.ex#L1)

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)

# `event`

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

# `delete_session`

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

Deletes a session by index or ID.

# `execute`

```elixir
@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`

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

# `list_sessions`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

Returns the installed Gemini CLI version string.

---

*Consult [api-reference.md](api-reference.md) for complete listing*