apiari-codex-sdk

Rust SDK for the OpenAI Codex CLI — spawn codex exec and stream JSONL events.

Not a direct API client. This crate spawns the codex CLI as a subprocess — the CLI handles authentication, tool execution, file access, and sandboxing.

Quick Start

use apiari_codex_sdk::{CodexClient, ExecOptions, Event, Item};

#[tokio::main]
async fn main() -> apiari_codex_sdk::Result<()> {
    let client = CodexClient::new();
    let mut execution = client.exec(
        "List files in the current directory",
        ExecOptions {
            model: Some("o4-mini".into()),
            full_auto: true,
            ..Default::default()
        },
    ).await?;

    while let Some(event) = execution.next_event().await? {
        match &event {
            Event::ItemCompleted { item: Item::AgentMessage { text, .. } } => {
                if let Some(text) = text {
                    println!("{text}");
                }
            }
            Event::TurnCompleted { usage } => {
                if let Some(u) = usage {
                    println!("Tokens: {} in, {} out", u.input_tokens, u.output_tokens);
                }
            }
            _ => {}
        }
    }
    Ok(())
}

Add to your Cargo.toml:

[dependencies]
apiari-codex-sdk = "0.1"

Requires the codex CLI on $PATH (or use CodexClient::with_cli_path).

Execution Model

The SDK uses a unidirectional, single-shot protocol. Each execution is one prompt in, one event stream out. Stdin is /dev/null.

┌─────────┐    CLI args (prompt)        ┌───────────┐
│   SDK   │ ────── exec() ────────────► │  codex    │
│         │                             │  CLI      │
│         │ ◄──── next_event() ──────── │  (stdout) │
└─────────┘       JSONL stream          └───────────┘
                                        stdin = /dev/null

Key properties:

• One prompt per execution — the prompt is a CLI argument, not streamed.
• Real-time event streaming — ItemUpdated gives incremental text. Render it live.
• No mid-execution input — you cannot send messages during an execution.
• Tool execution is internal — codex runs commands, edits files, and searches the web on its own. The SDK observes these as CommandExecution, FileChange, WebSearch items.
• interrupt() cancels the current execution via SIGINT.
• Resume for multi-turn — save the thread_id from ThreadStarted and pass it to exec_resume().

Multi-Turn Chat

Each user message is a separate execution that resumes the previous session:

// First message
let mut exec1 = client.exec("Set up a new Rust project", opts).await?;
let mut thread_id = None;
while let Some(event) = exec1.next_event().await? {
    if let Event::ThreadStarted { thread_id: tid } = &event {
        thread_id = Some(tid.clone());
    }
    // ... handle events ...
}

// Follow-up — resumes the same session
let mut exec2 = client.exec_resume("Now add serde", ResumeOptions {
    session_id: thread_id,
    full_auto: true,
    ..Default::default()
}).await?;

Codex SDK vs Claude SDK

Event Types

Item Types

Architecture

src/
  lib.rs          # Re-exports
  client.rs       # CodexClient + Execution handle
  options.rs      # ExecOptions, ResumeOptions, SandboxMode, ApprovalPolicy
  transport.rs    # ReadOnlyTransport — spawn, recv, interrupt, kill
  types.rs        # Event, Item, Usage
  error.rs        # SdkError + Result alias
tests/
  integration.rs  # Live CLI tests (#[ignore] by default)

Apiari Ecosystem

This crate is part of the Apiari tooling ecosystem:

• apiari-codex-sdk — Codex CLI SDK (this crate)
• apiari-claude-sdk — Claude Code SDK

License

MIT