Crate codex_wrapper

Expand description

A type-safe Codex CLI wrapper for Rust.

codex-wrapper provides a builder-pattern interface for invoking the codex CLI programmatically. It follows the same design philosophy as claude-wrapper and docker-wrapper: each CLI subcommand is a builder struct that produces typed output.

§Quick Start

use codex_wrapper::{Codex, CodexCommand, ExecCommand, SandboxMode};

let codex = Codex::builder().build()?;

let output = ExecCommand::new("summarize this repository")
    .sandbox(SandboxMode::WorkspaceWrite)
    .ephemeral()
    .execute(&codex)
    .await?;

println!("{}", output.stdout);

§Defaults

Type	Default variant
`SandboxMode`	`SandboxMode::WorkspaceWrite`
`ApprovalPolicy`	`ApprovalPolicy::OnRequest`

§Two-Layer Builder

The Codex client holds shared config (binary path, env vars, timeout, retry policy). Command builders hold per-invocation options and call execute(&codex).

use codex_wrapper::{Codex, CodexCommand, ExecCommand, ApprovalPolicy, RetryPolicy};
use std::time::Duration;

// Configure once, reuse across commands
let codex = Codex::builder()
    .env("OPENAI_API_KEY", "sk-...")
    .timeout_secs(300)
    .retry(RetryPolicy::new().max_attempts(3).exponential())
    .build()?;

// Each command is a separate builder
let output = ExecCommand::new("fix the failing tests")
    .model("o3")
    .approval_policy(ApprovalPolicy::Never)
    .skip_git_repo_check()
    .ephemeral()
    .execute(&codex)
    .await?;

§JSONL Output Parsing

Use execute_json_lines() to get structured events from --json mode:

use codex_wrapper::{Codex, ExecCommand};

let codex = Codex::builder().build()?;
let events = ExecCommand::new("what is 2+2?")
    .ephemeral()
    .execute_json_lines(&codex)
    .await?;

for event in &events {
    println!("{}: {:?}", event.event_type, event.extra);
}

§Available Commands

Command	CLI equivalent
`ExecCommand`	`codex exec <prompt>`
`ExecResumeCommand`	`codex exec resume`
`ReviewCommand`	`codex exec review`
`ResumeCommand`	`codex resume`
`ForkCommand`	`codex fork`
`LoginCommand`	`codex login`
`LoginStatusCommand`	`codex login status`
`LogoutCommand`	`codex logout`
`McpListCommand`	`codex mcp list`
`McpGetCommand`	`codex mcp get`
`McpAddCommand`	`codex mcp add`
`McpRemoveCommand`	`codex mcp remove`
`McpLoginCommand`	`codex mcp login`
`McpLogoutCommand`	`codex mcp logout`
`McpServerCommand`	`codex mcp-server`
`CompletionCommand`	`codex completion`
`SandboxCommand`	`codex sandbox`
`ApplyCommand`	`codex apply`
`FeaturesListCommand`	`codex features list`
`FeaturesEnableCommand`	`codex features enable`
`FeaturesDisableCommand`	`codex features disable`
`VersionCommand`	`codex --version`
`RawCommand`	Escape hatch for arbitrary args

§Error Handling

All commands return Result<T>, with typed errors via thiserror:

use codex_wrapper::{Codex, CodexCommand, ExecCommand, Error};

let codex = Codex::builder().build()?;
match ExecCommand::new("test").execute(&codex).await {
    Ok(output) => println!("{}", output.stdout),
    Err(Error::CommandFailed { stderr, exit_code, .. }) => {
        eprintln!("failed (exit {}): {}", exit_code, stderr);
    }
    Err(Error::Timeout { .. }) => eprintln!("timed out"),
    Err(e) => eprintln!("{e}"),
}

§Features

json (enabled by default) - JSONL output parsing via serde_json

Re-exports§

pub use command::CodexCommand;
pub use command::apply::ApplyCommand;
pub use command::completion::CompletionCommand;
pub use command::completion::Shell;
pub use command::exec::ExecCommand;
pub use command::exec::ExecResumeCommand;
pub use command::features::FeaturesDisableCommand;
pub use command::features::FeaturesEnableCommand;
pub use command::features::FeaturesListCommand;
pub use command::fork::ForkCommand;
pub use command::login::LoginCommand;
pub use command::login::LoginStatusCommand;
pub use command::login::LogoutCommand;
pub use command::mcp::McpAddCommand;
pub use command::mcp::McpGetCommand;
pub use command::mcp::McpListCommand;
pub use command::mcp::McpLoginCommand;
pub use command::mcp::McpLogoutCommand;
pub use command::mcp::McpRemoveCommand;
pub use command::mcp_server::McpServerCommand;
pub use command::raw::RawCommand;
pub use command::resume::ResumeCommand;
pub use command::review::ReviewCommand;
pub use command::sandbox::SandboxCommand;
pub use command::sandbox::SandboxPlatform;
pub use command::version::VersionCommand;
pub use error::Error;
pub use error::Result;
pub use exec::CommandOutput;
pub use retry::BackoffStrategy;
pub use retry::RetryPolicy;
pub use version::CliVersion;
pub use version::VersionParseError;
pub use types::*;

Modules§

command: Command builders for every Codex CLI subcommand.
error: Error types for codex-wrapper.
exec: Process execution layer for spawning and communicating with the codex binary, including timeout and retry support.
retry
types: Domain types shared across commands: enums for CLI options, version parsing, and structured JSONL events.
version: Version parsing and comparison utilities.

Structs§

Codex: Shared Codex CLI client configuration.
CodexBuilder: Builder for creating a Codex client.