Struct CodexClient 

pub struct CodexClient { /* private fields */ }

High-level client for interacting with codex exec.

Spawns the CLI with safe defaults (--skip-git-repo-check, temp working dirs unless working_dir is set, 120s timeout unless zero, ANSI colors off, RUST_LOG=error if unset), mirrors stdout by default, and returns whatever the CLI printed. See the crate docs for streaming/log tee/server patterns and example links.

Implementations

impl CodexClient

pub fn spawn_login_process(&self) -> Result<Child, CodexError>

Spawns a codex login session using the default ChatGPT OAuth flow.

The returned child inherits kill_on_drop so abandoning the handle cleans up the login helper.

pub fn spawn_device_auth_login_process(&self) -> Result<Child, CodexError>

Spawns a codex login --device-auth session.

The returned child inherits kill_on_drop so abandoning the handle cleans up the login helper.

pub fn spawn_with_api_key_login_process(&self) -> Result<Child, CodexError>

Spawns a codex login --with-api-key session (interactive API-key flow).

The returned child inherits kill_on_drop so abandoning the handle cleans up the login helper.

pub async fn spawn_mcp_login_process(&self) -> Result<Option<Child>, CodexError>

Spawns codex login --mcp when the probed binary advertises support.

Returns Ok(None) when the capability is unknown or unsupported so callers can degrade gracefully without attempting the flag.

pub async fn login_with_api_key( &self, api_key: impl AsRef<str>, ) -> Result<CodexAuthStatus, CodexError>

Logs in with a provided API key by invoking codex login --api-key <key>.

pub async fn login_status(&self) -> Result<CodexAuthStatus, CodexError>

Returns the current Codex authentication state by invoking codex login status.

pub async fn logout(&self) -> Result<CodexLogoutStatus, CodexError>

Removes cached credentials via codex logout.

impl CodexClient

pub fn start_app_server( &self, request: AppServerRequest, ) -> Result<Child, CodexError>

Spawns codex app-server with piped stdio for direct app-server integration.

pub fn start_app_server_proxy( &self, request: AppServerProxyRequest, ) -> Result<Child, CodexError>

Spawns codex app-server proxy with piped stdio for proxy/server integration.

pub async fn generate_app_server_bindings( &self, request: AppServerCodegenRequest, ) -> Result<AppServerCodegenOutput, CodexError>

Generates app-server bindings via codex app-server generate-ts or generate-json-schema.

Ensures the output directory exists, mirrors stdout/stderr according to the builder (mirror_stdout / quiet), and returns captured output plus the exit status. Non-zero exits bubble up as CodexError::NonZeroExit with stderr attached. Use AppServerCodegenRequest::prettier to format TypeScript output with a specific Prettier binary and request-level overrides for config/profile toggles.

impl CodexClient

pub async fn apply(&self) -> Result<ApplyDiffArtifacts, CodexError>

Applies a Codex diff by invoking codex apply <TASK_ID>.

Stdout mirrors to the console when mirror_stdout is enabled; stderr mirrors unless quiet is set. Output and exit status are always captured and returned, and RUST_LOG=error is injected for the child process when the environment variable is unset.

Convenience behavior: if CODEX_TASK_ID is set, it is appended as <TASK_ID>. When the environment variable is missing, the subprocess is still spawned and will typically exit non-zero with a “missing TASK_ID” error from the CLI.

pub async fn apply_task( &self, task_id: impl AsRef<str>, ) -> Result<ApplyDiffArtifacts, CodexError>

Applies a Codex diff by task id via codex apply <TASK_ID>.

pub async fn diff(&self) -> Result<ApplyDiffArtifacts, CodexError>

Shows a Codex Cloud task diff by invoking codex cloud diff <TASK_ID>.

Mirrors stdout/stderr using the same mirror_stdout/quiet defaults as apply, but always returns the captured output alongside the child exit status. Applies the same RUST_LOG defaulting behavior when the variable is unset.

Convenience behavior: if CODEX_TASK_ID is set, it is appended as <TASK_ID>. When the environment variable is missing, the subprocess is still spawned and will typically exit non-zero with a “missing TASK_ID” error from the CLI.

pub async fn cloud_diff_task( &self, task_id: impl AsRef<str>, ) -> Result<ApplyDiffArtifacts, CodexError>

Shows a Codex Cloud task diff by task id via codex cloud diff <TASK_ID>.

impl CodexClient

pub async fn cloud_overview( &self, request: CloudOverviewRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex cloud --help and returns captured output.

pub async fn cloud_list( &self, request: CloudListRequest, ) -> Result<CloudListOutput, CodexError>

Lists Codex Cloud tasks via codex cloud list.

pub async fn cloud_status( &self, request: CloudStatusRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Shows the status of a Codex Cloud task via codex cloud status <TASK_ID>.

pub async fn cloud_diff( &self, request: CloudDiffRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Shows the unified diff for a Codex Cloud task via codex cloud diff [--attempt N] <TASK_ID>.

pub async fn cloud_apply( &self, request: CloudApplyRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Applies the diff for a Codex Cloud task locally via codex cloud apply [--attempt N] <TASK_ID>.

pub async fn cloud_exec( &self, request: CloudExecRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Submits a new Codex Cloud task via codex cloud exec.

impl CodexClient

pub async fn debug( &self, request: DebugCommandRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex debug and returns captured output.

pub async fn debug_help( &self, request: DebugHelpRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex debug help [COMMAND]... and returns captured output.

pub async fn debug_app_server( &self, request: DebugAppServerRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex debug app-server and returns captured output.

pub async fn debug_app_server_help( &self, request: DebugAppServerHelpRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex debug app-server help [COMMAND]... and returns captured output.

pub async fn debug_app_server_send_message_v2( &self, request: DebugAppServerSendMessageV2Request, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex debug app-server send-message-v2 <USER_MESSAGE> and returns captured output.

pub async fn debug_models( &self, request: DebugModelsRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex debug models [--bundled] and returns captured output.

pub async fn debug_prompt_input( &self, request: DebugPromptInputRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex debug prompt-input [--image <FILE>...] [PROMPT] and returns captured output.

impl CodexClient

pub fn start_exec_server( &self, request: ExecServerRequest, ) -> Result<Child, CodexError>

Spawns codex exec-server with piped stdio for direct server integration.

impl CodexClient

pub async fn features( &self, request: FeaturesCommandRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex features and returns captured output.

pub async fn features_enable( &self, request: FeaturesEnableRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Enables a CLI feature via codex features enable <FEATURE>.

pub async fn features_disable( &self, request: FeaturesDisableRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Disables a CLI feature via codex features disable <FEATURE>.

pub async fn list_features( &self, request: FeaturesListRequest, ) -> Result<FeaturesListOutput, CodexError>

Lists CLI features via codex features list.

Requests JSON output when json(true) is set and falls back to parsing the text table when JSON is unavailable. Shared config/profile/search/approval overrides flow through via the request/builder, stdout/stderr are mirrored according to the builder, and non-zero exits surface as CodexError::NonZeroExit.

impl CodexClient

pub async fn fork_session( &self, request: ForkSessionRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex fork [OPTIONS] [SESSION_ID] [PROMPT] and returns captured output.

impl CodexClient

pub async fn help( &self, request: HelpCommandRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex <scope> help [COMMAND]... and returns captured output.

impl CodexClient

pub async fn mcp_overview( &self, request: McpOverviewRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex mcp --help and returns captured output.

pub async fn mcp_list( &self, request: McpListRequest, ) -> Result<McpListOutput, CodexError>

Lists configured MCP servers via codex mcp list.

pub async fn mcp_get( &self, request: McpGetRequest, ) -> Result<McpListOutput, CodexError>

Gets a configured MCP server entry via codex mcp get <NAME>.

pub async fn mcp_add( &self, request: McpAddRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Adds an MCP server configuration entry via codex mcp add.

pub async fn mcp_remove( &self, request: McpRemoveRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Removes an MCP server configuration entry via codex mcp remove <NAME>.

pub async fn mcp_logout( &self, request: McpLogoutRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Deauthenticates from an MCP server via codex mcp logout <NAME>.

pub fn spawn_mcp_oauth_login_process( &self, request: McpOauthLoginRequest, ) -> Result<Child, CodexError>

Spawns codex mcp login <NAME> [--scopes ...].

impl CodexClient

pub async fn plugin( &self, request: PluginCommandRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex plugin and returns captured output.

pub async fn plugin_help( &self, request: PluginHelpRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex plugin help [COMMAND]... and returns captured output.

pub async fn plugin_marketplace( &self, request: PluginMarketplaceCommandRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex plugin marketplace and returns captured output.

pub async fn plugin_marketplace_help( &self, request: PluginMarketplaceHelpRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex plugin marketplace help [COMMAND]... and returns captured output.

pub async fn plugin_marketplace_add( &self, request: PluginMarketplaceAddRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex plugin marketplace add <SOURCE> and returns captured output.

pub async fn plugin_marketplace_remove( &self, request: PluginMarketplaceRemoveRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex plugin marketplace remove <MARKETPLACE_NAME> and returns captured output.

pub async fn plugin_marketplace_upgrade( &self, request: PluginMarketplaceUpgradeRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex plugin marketplace upgrade [MARKETPLACE_NAME] and returns captured output.

impl CodexClient

pub async fn start_responses_api_proxy( &self, request: ResponsesApiProxyRequest, ) -> Result<ResponsesApiProxyHandle, CodexError>

Starts the codex responses-api-proxy helper with a supplied API key.

Forwards optional --port, --server-info, --http-shutdown, and --upstream-url flags. The API key is written to stdin immediately after spawn, stdout/stderr remain piped for callers to drain, and the returned handle owns the child process plus any --server-info path used.

impl CodexClient

pub async fn review( &self, request: ReviewCommandRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex review [OPTIONS] [PROMPT] and returns captured output.

pub async fn exec_review( &self, request: ExecReviewCommandRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex exec review [OPTIONS] [PROMPT] and returns captured output.

impl CodexClient

pub fn stdio_to_uds( &self, request: StdioToUdsRequest, ) -> Result<Child, CodexError>

Spawns codex stdio-to-uds <SOCKET_PATH> with piped stdio for manual relays.

Returns the child process so callers can write to stdin/read from stdout (e.g., to bridge a JSON-RPC transport over a Unix domain socket). Fails fast on empty socket paths and inherits the builder working directory when none is provided on the request.

pub async fn run_sandbox( &self, request: SandboxCommandRequest, ) -> Result<SandboxRun, CodexError>

Runs codex sandbox <platform> [--full-auto|--log-denials] [--config/--enable/--disable] -- <COMMAND...>.

Captures stdout/stderr and mirrors them according to the builder (mirror_stdout / quiet). Unlike apply/diff, non-zero exit codes are returned in SandboxRun::status without being wrapped in CodexError::NonZeroExit. macOS denial logging is enabled via SandboxCommandRequest::log_denials and ignored on other platforms. Linux uses the bundled codex-linux-sandbox helper; Windows sandboxing is experimental and relies on the upstream helper. The wrapper does not gate availability—unsupported installs will surface as non-zero statuses.

impl CodexClient

pub async fn send_prompt( &self, prompt: impl AsRef<str>, ) -> Result<String, CodexError>

Sends prompt to codex exec and returns its stdout (the final agent message) on success.

When .json(true) is enabled the CLI emits JSONL events (thread.started or thread.resumed, turn.started/turn.completed/turn.failed, item.created/item.updated, or error). The stream is mirrored to stdout unless .mirror_stdout(false); the returned string contains the buffered lines for offline parsing. For per-event handling, see crates/codex/examples/stream_events.rs.

use codex::CodexClient;
let client = CodexClient::builder().json(true).mirror_stdout(false).build();
let jsonl = client.send_prompt("Stream repo status").await?;
println!("{jsonl}");

pub async fn send_prompt_with( &self, request: ExecRequest, ) -> Result<String, CodexError>

Sends an exec request with per-call CLI overrides.

pub async fn stream_exec( &self, request: ExecStreamRequest, ) -> Result<ExecStream, ExecStreamError>

Streams structured JSONL events from codex exec --json.

Respects mirror_stdout (raw JSON echoing) and tees raw lines to json_event_log when configured on the builder or request. Returns an ExecStream with both the parsed event stream and a completion future that reports --output-last-message/schema paths.

pub async fn stream_exec_with_env_overrides( &self, request: ExecStreamRequest, env_overrides: &BTreeMap<String, String>, ) -> Result<ExecStream, ExecStreamError>

Streams JSONL events from codex exec --json with per-invocation environment overrides.

Env overrides are applied to the spawned Command for this invocation only and do not mutate the parent process environment. Overrides are applied after the wrapper’s internal environment injection (CODEX_HOME, CODEX_BINARY, default RUST_LOG) so callers can override those keys when needed.

pub async fn stream_exec_with_env_overrides_control( &self, request: ExecStreamRequest, env_overrides: &BTreeMap<String, String>, ) -> Result<ExecStreamControl, ExecStreamError>

Streams JSONL events from codex exec --json and returns a termination handle alongside the stream and completion future.

The termination handle is best-effort and idempotent; callers may request termination at any point after this returns.

pub async fn stream_exec_with_overrides( &self, request: ExecStreamRequest, overrides: CliOverridesPatch, ) -> Result<ExecStream, ExecStreamError>

Streams JSONL events with per-request CLI overrides.

pub async fn stream_resume( &self, request: ResumeRequest, ) -> Result<ExecStream, ExecStreamError>

Streams structured events from codex exec --json resume ....

pub async fn stream_resume_with_env_overrides_control( &self, request: ResumeRequest, env_overrides: &BTreeMap<String, String>, ) -> Result<ExecStreamControl, ExecStreamError>

Streams JSONL events from codex exec --json resume ... and returns a termination handle alongside the stream and completion future.

Env overrides are applied to the spawned Command for this invocation only and do not mutate the parent process environment.

pub async fn resume_session( &self, request: ResumeSessionRequest, ) -> Result<ApplyDiffArtifacts, CodexError>

Runs codex resume [OPTIONS] [SESSION_ID] [PROMPT] and returns captured output.

impl CodexClient

pub async fn check_execpolicy( &self, request: ExecPolicyCheckRequest, ) -> Result<ExecPolicyCheckResult, CodexError>

Evaluates a command against Starlark execpolicy files via codex execpolicy check.

Forwards repeatable --policy paths, optional --pretty, and builder/request CLI overrides (config/profile/approval/sandbox/local-provider/cd/search). Captures stdout/stderr according to the builder, returns parsed JSON, and surfaces non-zero exits as CodexError::NonZeroExit. Empty command argv returns CodexError::EmptyExecPolicyCommand.

impl CodexClient

pub fn builder() -> CodexClientBuilder

Returns a CodexClientBuilder preloaded with safe defaults.

pub fn codex_home_layout(&self) -> Option<CodexHomeLayout>

Returns the configured CODEX_HOME layout, if one was provided. This does not create any directories on disk; pair with CodexClientBuilder::create_home_dirs to control materialization.

pub async fn probe_capabilities(&self) -> CodexCapabilities

Probes the configured binary for version/build metadata and supported feature flags.

Results are cached per canonical binary path and invalidated when file metadata changes. Caller-supplied overrides (see CodexClientBuilder::capability_overrides) can short-circuit probes or layer hints; snapshots are still cached against the current binary fingerprint so changes on disk trigger revalidation. Missing fingerprints skip cache reuse to force a re-probe. Cache interaction follows the policy configured on the builder (see CodexClientBuilder::capability_cache_policy). Failures are logged and return conservative defaults so callers can gate optional flags.

pub async fn probe_capabilities_with_env_overrides( &self, env_overrides: &BTreeMap<String, String>, ) -> CodexCapabilities

Probes capabilities using per-invocation environment overrides.

Env overrides are applied after the wrapper’s internal environment injection so the probe observes the same effective environment as stream_*_with_env_overrides_control. Non-empty overrides bypass the process-wide capability cache to avoid polluting cached snapshots keyed only by binary path.

pub async fn probe_capabilities_with_policy( &self, cache_policy: CapabilityCachePolicy, ) -> CodexCapabilities

Probes capabilities with an explicit cache policy.

pub async fn update_advisory( &self, latest_releases: &CodexLatestReleases, ) -> CodexUpdateAdvisory

Computes an update advisory by comparing the probed Codex version against caller-supplied latest releases.

The crate does not fetch release metadata itself; hosts should populate CodexLatestReleases using their preferred update channel (npm, Homebrew, GitHub releases) and then call this helper. Results leverage the capability probe cache; callers with an existing CodexCapabilities snapshot can skip the probe by invoking update_advisory_from_capabilities.

Trait Implementations

impl Clone for CodexClient

fn clone(&self) -> CodexClient

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CodexClient

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

Formats the value using the given formatter.

impl Default for CodexClient

fn default() -> Self

Returns the “default value” for a type.