Struct ClientConfig 

pub struct ClientConfig {

    pub prompt: String,
    pub cli_path: Option<PathBuf>,
    pub cwd: Option<PathBuf>,
    pub model: Option<String>,
    pub system_prompt: Option<SystemPrompt>,
    pub max_turns: Option<u32>,
    pub allowed_tools: Vec<String>,
    pub disallowed_tools: Vec<String>,
    pub permission_mode: PermissionMode,
    pub can_use_tool: Option<CanUseToolCallback>,
    pub resume: Option<String>,
    pub hooks: Vec<HookMatcher>,
    pub mcp_servers: McpServers,
    pub message_callback: Option<MessageCallback>,
    pub env: HashMap<String, String>,
    pub verbose: bool,
    pub auth_method: Option<AuthMethod>,
    pub sandbox: bool,
    pub extra_args: BTreeMap<String, Option<String>>,
    pub connect_timeout: Option<Duration>,
    pub close_timeout: Option<Duration>,
    pub read_timeout: Option<Duration>,
    pub default_hook_timeout: Duration,
    pub version_check_timeout: Option<Duration>,
    pub stderr_callback: Option<Arc<dyn Fn(String) + Send + Sync>>,
}

Full configuration for a Gemini CLI session.

Built with the TypedBuilder pattern. Only prompt is required; all other fields have sensible defaults. Gemini-specific fields (auth_method, sandbox, extra_args) extend the common set.

Example

use gemini_cli_sdk::config::{ClientConfig, AuthMethod};

let config = ClientConfig::builder()
    .prompt("Hello, Gemini!")
    .model("gemini-2.5-flash")
    .auth_method(AuthMethod::ApiKey)
    .verbose(true)
    .build();

Fields

prompt: String

The prompt text sent to the CLI.

cli_path: Option<PathBuf>

Override the path to the gemini CLI binary. When None, the binary is located via PATH using which.

cwd: Option<PathBuf>

Working directory for the CLI subprocess. Defaults to the current process’s working directory when None.

model: Option<String>

Gemini model identifier (e.g., "gemini-2.5-pro").

system_prompt: Option<SystemPrompt>

Custom system prompt injected into the session.

max_turns: Option<u32>

Maximum number of agentic turns before the session is terminated.

allowed_tools: Vec<String>

Tool names the CLI is explicitly permitted to use. An empty list means all tools are allowed (subject to disallowed_tools).

disallowed_tools: Vec<String>

Tool names that are always denied, overriding allowed_tools.

permission_mode: PermissionMode

Global permission mode passed to the CLI via approval-mode flags.

can_use_tool: Option<CanUseToolCallback>

Fine-grained per-tool permission callback, evaluated before each tool execution. Takes precedence over permission_mode for individual calls.

resume: Option<String>

Session ID to resume. When set, the CLI is invoked with --resume.

hooks: Vec<HookMatcher>

Event hooks that fire at defined points in the session lifecycle.

mcp_servers: McpServers

MCP server configurations forwarded to the CLI at session creation.

message_callback: Option<MessageCallback>

Optional callback invoked for each message before it is yielded to the stream. Suitable for logging, persistence, or UI updates.

env: HashMap<String, String>

Additional environment variables injected into the CLI subprocess.

verbose: bool

Enable verbose CLI output (passes the --debug flag, or equivalent).

auth_method: Option<AuthMethod>

Authentication method for the Gemini CLI.

Auth is configured via environment variables rather than CLI flags:

• LoginWithGoogle — expects the user to have run gemini auth login.
• ApiKey — reads GEMINI_API_KEY from the environment.
• VertexAi — reads GOOGLE_CLOUD_PROJECT + ADC credentials.

This field does not generate CLI arguments in to_cli_args().

sandbox: bool

Run the session inside a sandbox.

extra_args: BTreeMap<String, Option<String>>

Arbitrary extra CLI flags. The map key becomes --{key}, the optional value is appended as a separate argument when Some.

connect_timeout: Option<Duration>

Timeout for the initial JSON-RPC connection handshake.

close_timeout: Option<Duration>

Grace period allowed for the CLI process to exit cleanly on shutdown.

read_timeout: Option<Duration>

Per-read timeout on the stdio transport. None means no timeout.

Note: This field is accepted for forward-compatibility but is not yet enforced by the transport layer. It is reserved for a future release.

default_hook_timeout: Duration

Default timeout budget given to each hook execution.

version_check_timeout: Option<Duration>

Timeout for the background CLI version check. None skips the check.

Note: This field is accepted for forward-compatibility but is not yet enforced by the transport layer. It is reserved for a future release.

stderr_callback: Option<Arc<dyn Fn(String) + Send + Sync>>

Optional callback that receives every line written to the CLI’s stderr. Useful for surfacing CLI-level warnings and errors to callers.

Implementations

impl ClientConfig

pub fn builder() -> ClientConfigBuilder<((), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), ())>

Create a builder for building ClientConfig. On the builder, call .prompt(...), .cli_path(...)(optional), .cwd(...)(optional), .model(...)(optional), .system_prompt(...)(optional), .max_turns(...)(optional), .allowed_tools(...)(optional), .disallowed_tools(...)(optional), .permission_mode(...)(optional), .can_use_tool(...)(optional), .resume(...)(optional), .hooks(...)(optional), .mcp_servers(...)(optional), .message_callback(...)(optional), .env(...)(optional), .verbose(...)(optional), .auth_method(...)(optional), .sandbox(...)(optional), .extra_args(...)(optional), .connect_timeout(...)(optional), .close_timeout(...)(optional), .read_timeout(...)(optional), .default_hook_timeout(...)(optional), .version_check_timeout(...)(optional), .stderr_callback(...)(optional) to set the values of the fields. Finally, call .build() to create the instance of ClientConfig.

impl ClientConfig

pub fn to_cli_args(&self) -> Vec<String>

Translate this configuration into CLI arguments for the Gemini binary.

The ACP mode flag (--experimental-acp) is always prepended. Remaining flags are derived from the fields that have non-default values.

Example

use gemini_cli_sdk::config::{ClientConfig, PermissionMode};

let config = ClientConfig::builder()
    .prompt("test")
    .permission_mode(PermissionMode::BypassPermissions)
    .build();

let args = config.to_cli_args();
assert!(args.contains(&"--yolo".to_string()));