{"id":49504896,"url":"https://github.com/nshkrdotcom/gemini_cli_sdk","last_synced_at":"2026-05-01T14:34:21.455Z","repository":{"id":338361491,"uuid":"1155849699","full_name":"nshkrdotcom/gemini_cli_sdk","owner":"nshkrdotcom","description":"An Elixir SDK for the Gemini CLI — Build AI-powered applications with Google Gemini via a robust, idiomatic wrapper around the Gemini CLI. Features streaming, structured output, session management, model selection, and OTP supervision tree integration for production-grade Gemini-powered Elixir apps.","archived":false,"fork":false,"pushed_at":"2026-04-23T21:19:22.000Z","size":341,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T22:22:50.365Z","etag":null,"topics":["ai-agent","ai-sdk","ai-tools","beam","cli-wrapper","elixir","elixir-library","erlang","functional-programming","gemini","gemini-api","gemini-cli","generative-ai","google-ai","google-gemini","hex-package","large-language-models","llm","machine-learning","nshkr-ai-sdk"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nshkrdotcom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-12T01:11:22.000Z","updated_at":"2026-04-23T21:19:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"73c31266-06cd-400b-9583-ae5a43d64e25","html_url":"https://github.com/nshkrdotcom/gemini_cli_sdk","commit_stats":null,"previous_names":["nshkrdotcom/gemini_cli_sdk"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/nshkrdotcom/gemini_cli_sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fgemini_cli_sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fgemini_cli_sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fgemini_cli_sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fgemini_cli_sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nshkrdotcom","download_url":"https://codeload.github.com/nshkrdotcom/gemini_cli_sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fgemini_cli_sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32501403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-sdk","ai-tools","beam","cli-wrapper","elixir","elixir-library","erlang","functional-programming","gemini","gemini-api","gemini-cli","generative-ai","google-ai","google-gemini","hex-package","large-language-models","llm","machine-learning","nshkr-ai-sdk"],"created_at":"2026-05-01T14:34:20.261Z","updated_at":"2026-05-01T14:34:21.430Z","avatar_url":"https://github.com/nshkrdotcom.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/gemini_cli_sdk.svg\" alt=\"GeminiCliSdk\" width=\"200\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hex.pm/packages/gemini_cli_sdk\"\u003e\u003cimg src=\"https://img.shields.io/hexpm/v/gemini_cli_sdk.svg\" alt=\"Hex.pm Version\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://hexdocs.pm/gemini_cli_sdk\"\u003e\u003cimg src=\"https://img.shields.io/badge/hex-docs-blue.svg\" alt=\"HexDocs\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://hex.pm/packages/gemini_cli_sdk\"\u003e\u003cimg src=\"https://img.shields.io/hexpm/l/gemini_cli_sdk.svg\" alt=\"License\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://hex.pm/packages/gemini_cli_sdk\"\u003e\u003cimg src=\"https://img.shields.io/hexpm/dt/gemini_cli_sdk.svg\" alt=\"Downloads\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# GeminiCliSdk\n\nAn Elixir SDK for the [Gemini CLI](https://github.com/google-gemini/gemini-cli) -- build AI-powered applications with Google Gemini through a robust, idiomatic wrapper around the Gemini command-line interface.\n\n## Documentation Menu\n\n- `README.md` - installation, quick start, and runtime boundaries\n- `guides/getting-started.md` - first execution and session flows\n- `guides/options.md` - runtime and CLI option shaping\n- `guides/models.md` - Gemini model selection behavior\n- `guides/architecture.md` - shared core runtime ownership\n- `guides/testing.md` - local validation workflow\n\n## Features\n\n- **Streaming** -- Lazy `Stream`-based API with typed event structs and backpressure\n- **Synchronous** -- Simple `{:ok, text} | {:error, error}` for request/response patterns\n- **Session Management** -- List, resume, and delete conversation sessions\n- **Shared Core Runtime** -- Streaming and one-shot command execution now run on `cli_subprocess_core` while preserving Gemini-specific public types and entrypoints\n- **Subprocess Safety** -- Built on `cli_subprocess_core`, which now routes the covered local session lane through the `CliSubprocessCore` transport facade while keeping Gemini-facing types and cleanup semantics stable\n- **Typed Events** -- 6 event types (init, message, tool_use, tool_result, error, result) parsed from JSONL\n- **Full Options** -- Model selection, explicit CLI command paths, YOLO mode, sandboxing, extensions, settings profiles, and more\n- **OTP Integration** -- Application supervision tree with TaskSupervisor for async I/O\n\n## Installation\n\nAdd `gemini_cli_sdk` to your dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:gemini_cli_sdk, \"~\u003e 0.2.0\"}\n  ]\nend\n```\n\n**Prerequisites**: The [Gemini CLI](https://github.com/google-gemini/gemini-cli) must be installed and authenticated.\n\n## Quick Start\n\n### Streaming\n\n```elixir\nGeminiCliSdk.execute(\"Explain GenServer in 3 sentences\")\n|\u003e Enum.each(fn event -\u003e\n  case event do\n    %GeminiCliSdk.Types.MessageEvent{role: \"assistant\", content: text} -\u003e\n      IO.write(text)\n    _ -\u003e\n      :ok\n  end\nend)\n```\n\n### Synchronous\n\n```elixir\n{:ok, response} = GeminiCliSdk.run(\"What is Elixir?\")\nIO.puts(response)\n```\n\n### With Options\n\n```elixir\nopts = %GeminiCliSdk.Options{\n  model: GeminiCliSdk.Models.fast_model(),\n  yolo: true,\n  skip_trust: true,\n  timeout_ms: 60_000\n}\n\n{:ok, response} = GeminiCliSdk.run(\"Refactor this function\", opts)\n```\n\n### Sessions\n\n```elixir\n# List sessions\n{:ok, sessions} = GeminiCliSdk.list_sessions()\n\n# Resume a session\nGeminiCliSdk.resume_session(\"abc123\", %GeminiCliSdk.Options{}, \"Continue\")\n|\u003e Enum.each(fn event -\u003e\n  case event do\n    %GeminiCliSdk.Types.MessageEvent{role: \"assistant\", content: text} -\u003e\n      IO.write(text)\n    _ -\u003e :ok\n  end\nend)\n```\n\n## Event Types\n\n| Struct | Description |\n|--------|-------------|\n| `Types.InitEvent` | Session initialized with `session_id` and `model` |\n| `Types.MessageEvent` | Message chunk with `role` and `content` |\n| `Types.ToolUseEvent` | Tool invocation with `tool_name` and `parameters` |\n| `Types.ToolResultEvent` | Tool result with `tool_id` and `output` |\n| `Types.ErrorEvent` | Error with `severity` and `message` |\n| `Types.ResultEvent` | Final result with `status` and `stats` |\n\nAll stream-event structs are now schema-backed. Known fields are normalized\nthrough `Zoi`, forward-compatible unknown fields are preserved in `extra`, and\nthe event modules expose `to_map/1` for projection back to wire shape.\n\n## Architecture\n\nGeminiCliSdk preserves its public API while running the common CLI session lane on\n`cli_subprocess_core`.\n\nThe current layering is:\n\n```text\nGeminiCliSdk public API\n  -\u003e GeminiCliSdk.Stream / GeminiCliSdk.Runtime.CLI\n  -\u003e CliSubprocessCore.Session\n  -\u003e CliSubprocessCore transport facade\n  -\u003e gemini CLI\n\nGeminiCliSdk command helpers\n  -\u003e CliSubprocessCore.Command.run/2\n  -\u003e CliSubprocessCore process lane (local) / CliSubprocessCore transport facade (non-local)\n  -\u003e gemini CLI\n```\n\n`GeminiCliSdk.Runtime.CLI` is the Gemini runtime kit. It starts\ncore sessions, preserves Gemini CLI command resolution and option shaping, and\nprojects normalized core events back into `GeminiCliSdk.Types.*`.\n\nNo Gemini-owned raw transport module remains for the covered lane. The SDK keeps\nGemini-specific command resolution, option shaping, and event projection above\nthe shared core and Execution Plane-backed lower transport seam.\n\n## Ownership Boundary\n\nThe Wave 6 boundary for Gemini is:\n\n- shared session lifecycle\n- shared JSONL parsing and normalized event flow\n- shared local session transport ownership through the `CliSubprocessCore` transport facade\n- shared command execution through `CliSubprocessCore.Command`, with local one-shot\n  execution routed through the `CliSubprocessCore` process lane and non-local\n  execution routed through the `CliSubprocessCore` transport facade\n\nPublic Gemini entrypoints stay the same:\n\n- `GeminiCliSdk.execute/2`\n- `GeminiCliSdk.run/2`\n- `GeminiCliSdk.resume_session/3`\n- `GeminiCliSdk.list_sessions/1`\n- `GeminiCliSdk.delete_session/2`\n\nGemini CLI resolution, option shaping, and public result/error mapping remain in\nthis repo above the shared core.\n\nNo separate Gemini-owned common subprocess runtime remains here. Repo-local\nownership is limited to Gemini CLI discovery, argument shaping, settings\nprofiles, and typed event/result projection above the shared core.\n\nThe release and composition model is:\n\n- the common Gemini profile stays built into `cli_subprocess_core`\n- `gemini_cli_sdk` remains the provider-specific runtime-kit package above that\n  shared core\n- no extra ASM extension seam is introduced unless Gemini later proves a real\n  richer provider-native surface beyond the current common lane\n\nIf `gemini_cli_sdk` is installed alongside `agent_session_manager`, ASM\nreports Gemini runtime availability in\n`ASM.Extensions.ProviderSDK.capability_report/0` but keeps\n`namespaces: []` because Gemini currently composes through the common ASM\nsurface only.\n\n## Centralized Model Selection\n\n`gemini_cli_sdk` now consumes model payloads resolved by\n`cli_subprocess_core`. The SDK no longer owns active fallback/defaulting\npolicy for provider selection.\n\nAuthoritative policy surface:\n\n- `CliSubprocessCore.ModelRegistry.resolve/3`\n- `CliSubprocessCore.ModelRegistry.validate/2`\n- `CliSubprocessCore.ModelRegistry.default_model/2`\n- `CliSubprocessCore.ModelRegistry.build_arg_payload/3`\n- `CliSubprocessCore.ModelInput.normalize/3`\n\nGemini-side responsibility is limited to:\n\n- carrying the resolved `model_payload` on `GeminiCliSdk.Options`\n- projecting the resolved model for UX and metadata\n- rendering `--model` only when the resolved value is non-empty\n- using the shared core registry default when no explicit model input was supplied\n\nNo repo-local Gemini model fallback remains.\n\n`GeminiCliSdk.Options.validate!/1` canonicalizes explicit payloads through the\nshared core boundary. A `CliSubprocessCore.ModelRegistry.Selection` is the\npreferred form, and `Map.from_struct(selection)` is normalized back into the\nsame canonical payload when callers already have a serialized struct map.\n\n## Promotion Path And Provider-Native Features\n\n`gemini_cli_sdk` is the authoritative home for Gemini-native CLI settings and\nflags. Gemini settings profiles, extension flags, allowed-tool flags, MCP\nserver-name flags, approval mode, skip-trust, and provider CLI sandbox flags are\nSDK-owned behavior. They must not be promoted into generic ASM options unless\nequivalent behavior is proven across Claude, Codex, Gemini, and Amp.\n\nSDK-direct live verification lives in\n`examples/promotion_path/sdk_direct_gemini.exs`. It uses the Gemini SDK API\nwithout importing ASM, passes keyword `execution_surface` input, and demonstrates\nthe SDK-native `GeminiCliSdk.SettingsProfiles.plain_response/0` profile:\n\n```bash\nmix run examples/promotion_path/sdk_direct_gemini.exs \\\n  --model gemini-3.1-flash-lite-preview \\\n  --prompt \"Reply with exactly: gemini sdk direct ok\"\n```\n\nProvider-native feature evidence is tracked in\n`guides/provider_behavior_manifest.md`. Add or update that manifest before\ntranslating any new Gemini-specific setting or CLI flag.\n\n## Documentation\n\nFull documentation is available at [HexDocs](https://hexdocs.pm/gemini_cli_sdk).\n\n- [Getting Started](https://hexdocs.pm/gemini_cli_sdk/getting-started.html)\n- [Streaming Guide](https://hexdocs.pm/gemini_cli_sdk/streaming.html)\n- [Options Reference](https://hexdocs.pm/gemini_cli_sdk/options.html)\n- [Error Handling](https://hexdocs.pm/gemini_cli_sdk/error-handling.html)\n- [Architecture](https://hexdocs.pm/gemini_cli_sdk/architecture.html)\n\n## Examples\n\nSee the `examples/` directory for live examples that run against the real Gemini CLI:\n\n```bash\nmix run examples/simple_prompt.exs\nmix run examples/streaming.exs\nbash examples/run_all.sh\n```\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n## Model Selection Contract\n\nSee [Centralized Model Selection](#centralized-model-selection). The Gemini SDK\nrenders provider transport args from the shared resolved payload and does not\nemit nil/null/blank model values.\n## Session Listing And Resume Surfaces\n\nGemini now exposes a typed session-history projection for orchestration layers that need to recover\nan existing CLI conversation instead of replaying prompts from scratch.\n\n- `GeminiCliSdk.list_session_entries/1` parses the CLI session list into typed\n  `%GeminiCliSdk.Session.Entry{}` values\n- `GeminiCliSdk.Runtime.CLI.capabilities/0` publishes `:session_history`, `:session_resume`,\n  `:session_pause`, and `:session_intervene`\n- `GeminiCliSdk.Runtime.CLI.list_provider_sessions/1` projects those typed entries into the common\n  runtime-neutral list shape used by higher layers\n\nThe runtime also now carries `system_prompt` through the validated options\nsurface as prompt preamble text so the caller can resume with the same\ninstruction context it started with.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshkrdotcom%2Fgemini_cli_sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnshkrdotcom%2Fgemini_cli_sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshkrdotcom%2Fgemini_cli_sdk/lists"}