Struct CodexClientBuilder 

pub struct CodexClientBuilder { /* private fields */ }

Builder for crate::CodexClient.

CLI parity planning and implementation history lives under .archived/project_management/next/ (see .archived/project_management/next/codex-cli-parity/) and the parity ADRs in docs/adr/.

Implementations

impl CodexClientBuilder

pub fn new() -> Self

Starts a new builder with default values.

pub fn binary(self, binary: impl Into<PathBuf>) -> Self

Sets the path to the Codex binary.

Defaults to CODEX_BINARY when present or codex on PATH. Use this to pin a packaged binary, e.g. the path returned from crate::resolve_bundled_binary when your app ships Codex inside an isolated bundle.

pub fn codex_home(self, home: impl Into<PathBuf>) -> Self

Sets a custom CODEX_HOME path that will be applied per command. Directories are created by default; disable via Self::create_home_dirs.

pub fn create_home_dirs(self, enable: bool) -> Self

Controls whether the CODEX_HOME directory tree should be created if missing. Defaults to true when Self::codex_home is set.

pub fn model(self, model: impl Into<String>) -> Self

Sets the model that should be used for every codex exec call.

pub fn timeout(self, timeout: Duration) -> Self

Overrides the maximum amount of time to wait for Codex to respond.

pub fn color_mode(self, color_mode: ColorMode) -> Self

Controls whether Codex may emit ANSI colors (--color). Defaults to ColorMode::Never.

pub fn working_dir(self, dir: impl Into<PathBuf>) -> Self

Forces Codex to run with the provided working directory instead of a fresh temp dir.

pub fn add_dir(self, path: impl Into<PathBuf>) -> Self

Requests that codex exec include one or more --add-dir flags when the probed binary supports them. Unsupported or unknown capability results skip the flag to avoid CLI errors.

pub fn add_dirs<I, P>(self, dirs: I) -> Self

where I: IntoIterator<Item = P>, P: Into<PathBuf>,

Replaces the current add-dir list with the provided collection.

pub fn image(self, path: impl Into<PathBuf>) -> Self

Adds an image to the prompt by passing --image <path> to codex exec.

pub fn images<I, P>(self, images: I) -> Self

where I: IntoIterator<Item = P>, P: Into<PathBuf>,

Replaces the current image list with the provided collection.

pub fn json(self, enable: bool) -> Self

Enables Codex’s JSONL output mode (--json).

Prompts are piped via stdin when enabled. Events include thread.started (or thread.resumed when continuing), turn.started/turn.completed/turn.failed, and item.created/item.updated with item.type such as agent_message or reasoning. Pair with .mirror_stdout(false) if you plan to parse the stream instead of just mirroring it.

pub fn output_schema(self, enable: bool) -> Self

Requests the --output-schema flag when the probed binary reports support. When capability detection is inconclusive, the flag is skipped to maintain compatibility with older releases.

pub fn quiet(self, enable: bool) -> Self

Suppresses mirroring Codex stderr to the console.

pub fn mirror_stdout(self, enable: bool) -> Self

Controls whether Codex stdout should be mirrored to the console while also being captured. Disable this when you plan to parse JSONL output or tee the stream to a log file (see crates/codex/examples/stream_with_log.rs).

pub fn json_event_log(self, path: impl Into<PathBuf>) -> Self

Tees each JSONL event line from crate::CodexClient::stream_exec into a log file. Logs append to existing files, flush after each line, and create parent directories as needed. crate::ExecStreamRequest::json_event_log overrides this default per request.

pub fn config_override( self, key: impl Into<String>, value: impl Into<String>, ) -> Self

Adds a --config key=value override that will be applied to every Codex invocation.

pub fn config_override_raw(self, raw: impl Into<String>) -> Self

Adds a preformatted --config key=value override without parsing the input.

pub fn config_overrides<I, K, V>(self, overrides: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: Into<String>, V: Into<String>,

Replaces the config overrides with the provided collection.

pub fn profile(self, profile: impl Into<String>) -> Self

Selects a Codex config profile (--profile).

pub fn reasoning_effort(self, effort: ReasoningEffort) -> Self

Sets model_reasoning_effort via --config.

pub fn reasoning_summary(self, summary: ReasoningSummary) -> Self

Sets model_reasoning_summary via --config.

pub fn reasoning_verbosity(self, verbosity: ModelVerbosity) -> Self

Sets model_verbosity via --config.

pub fn reasoning_summary_format(self, format: ReasoningSummaryFormat) -> Self

Sets model_reasoning_summary_format via --config.

pub fn supports_reasoning_summaries(self, enable: bool) -> Self

Sets model_supports_reasoning_summaries via --config.

pub fn auto_reasoning_defaults(self, enable: bool) -> Self

Controls whether GPT-5* reasoning defaults should be injected automatically.

pub fn approval_policy(self, policy: ApprovalPolicy) -> Self

Sets the approval policy for Codex subprocesses.

pub fn sandbox_mode(self, mode: SandboxMode) -> Self

Sets the sandbox mode for Codex subprocesses.

pub fn full_auto(self, enable: bool) -> Self

Applies the --full-auto safety override unless explicit sandbox/approval options are set.

pub fn dangerously_bypass_approvals_and_sandbox(self, enable: bool) -> Self

Applies the --dangerously-bypass-approvals-and-sandbox override.

pub fn cd(self, dir: impl Into<PathBuf>) -> Self

Applies --cd <dir> to Codex invocations while keeping the process cwd set to working_dir.

pub fn remote(self, remote: impl Into<String>) -> Self

Selects a remote Codex target (--remote).

pub fn remote_auth_token_env(self, env_var: impl Into<String>) -> Self

Selects the env var that provides the remote auth token (--remote-auth-token-env).

pub fn local_provider(self, provider: LocalProvider) -> Self

Selects a local provider backend (--local-provider).

pub fn oss(self, enable: bool) -> Self

Requests the CLI --oss flag to favor OSS/local backends when available.

pub fn enable_feature(self, name: impl Into<String>) -> Self

Adds a --enable <feature> toggle to Codex invocations.

pub fn disable_feature(self, name: impl Into<String>) -> Self

Adds a --disable <feature> toggle to Codex invocations.

pub fn search(self, enable: bool) -> Self

Controls whether --search is passed through to Codex.

pub fn capability_overrides(self, overrides: CapabilityOverrides) -> Self

Supplies manual capability data to skip probes or adjust feature flags.

pub fn capability_feature_overrides( self, overrides: CapabilityFeatureOverrides, ) -> Self

Convenience to apply feature overrides or vendor hints without touching versions.

pub fn capability_feature_hints(self, features: CodexFeatureFlags) -> Self

Convenience to opt into specific feature flags while leaving other probes intact.

pub fn capability_snapshot(self, snapshot: CodexCapabilities) -> Self

Supplies a precomputed capability snapshot for pinned or bundled Codex builds. Combine with write_capabilities_snapshot / read_capabilities_snapshot to persist probe results between processes.

pub fn capability_version_override(self, version: CodexVersionInfo) -> Self

Overrides the probed version data with caller-provided metadata.

pub fn capability_cache_policy(self, policy: CapabilityCachePolicy) -> Self

Controls how capability probes interact with the in-process cache. Use crate::CapabilityCachePolicy::Refresh to enforce a TTL/backoff when binaries are hot-swapped without changing fingerprints.

pub fn bypass_capability_cache(self, bypass: bool) -> Self

Convenience to bypass the capability cache when a fresh snapshot is required. Bypass skips cache reads and writes for the probe.

pub fn build(self) -> CodexClient

Builds the crate::CodexClient.

Trait Implementations

impl Clone for CodexClientBuilder

fn clone(&self) -> CodexClientBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CodexClientBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CodexClientBuilder

fn default() -> Self

Returns the “default value” for a type.