Struct ExecCommand

Source

pub struct ExecCommand { /* private fields */ }

Expand description

Run Codex non-interactively (codex exec <prompt>).

This is the primary command for programmatic use. It supports the full range of exec flags: model selection, sandbox policy, images, config overrides, feature flags, JSON output, and more.

§Example

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

let codex = Codex::builder().build()?;
let output = ExecCommand::new("fix the failing test")
    .model("o3")
    .sandbox(SandboxMode::WorkspaceWrite)
    .ephemeral()
    .execute(&codex)
    .await?;
println!("{}", output.stdout);

Implementations§

Source §

impl ExecCommand

Source

pub fn new(prompt: impl Into<String>) -> Self

Create a new exec command with the given prompt.

Source

pub fn from_stdin(prompt: impl Into<String>) -> Self

Send the prompt on stdin instead of as an argument (codex exec -).

Shorthand for new followed by prompt_via_stdin. Use it for prompts that are large or awkward to pass through argv.

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

let codex = Codex::builder().build()?;
let diff = std::fs::read_to_string("huge.patch")?;
let output = ExecCommand::from_stdin(format!("Review this patch:\n{diff}"))
    .execute(&codex)
    .await?;

Before 0.3 this took no argument and set the prompt to the literal -, which could not work: nothing wrote to the child’s stdin, so the CLI saw an immediate EOF and an empty prompt (#81).

Source

pub fn prompt_via_stdin(self) -> Self

Deliver this command’s prompt on stdin rather than in argv.

The prompt is replaced by - in the argument list and written to the child’s stdin instead.

Retry does not apply to a stdin prompt, and any policy set on the command or the client is ignored for it. A second attempt would need to write the prompt again, into a pipe the first attempt has already consumed, and retrying with an empty stdin would be worse than not retrying.

Source

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

Override a config key (-c key=value).

May be called multiple times to set several keys. Because -c is last-wins, a key set here overrides the same key set by approval_policy or search_mode.

Source

pub fn approval_policy(self, policy: impl Into<ApprovalPolicyConfig>) -> Self

Set when the model asks for approval (-c approval_policy="<value>").

codex-cli 0.145.0 removed --ask-for-approval from codex exec; the config key is the supported equivalent. Accepts an ApprovalPolicy directly, or an ApprovalPolicyConfig for the two values the flag never took.

use codex_wrapper::{ApprovalPolicyConfig, CodexCommand, ExecCommand};

let args = ExecCommand::new("hi")
    .approval_policy(ApprovalPolicyConfig::Never)
    .args();
assert!(args.windows(2).any(|w| w == ["-c", "approval_policy=\"never\""]));

Source

pub fn search(self) -> Self

Enable live web search.

Shorthand for search_mode(WebSearchMode::Live), which is what the removed --search flag meant.

Source

pub fn search_mode(self, mode: WebSearchMode) -> Self

Set the web search mode (-c web_search="<value>").

codex-cli 0.145.0 removed --search from codex exec; the config key is the supported equivalent, and it is an enum rather than the flag’s boolean.

Source

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

Enable an optional feature flag (--enable <feature>).

May be called multiple times.

Source

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

Disable an optional feature flag (--disable <feature>).

May be called multiple times.

Source

pub fn rollout_budget(self, budget: RolloutBudgetConfig) -> Self

Enforce a Codex-native rollout-unit budget for this execution.

Codex checks the budget at response boundaries, so one response can cross the limit before the run stops. Codex 0.145-0.146 use weighted output and non-cached input; starting with 0.147, a provider-supplied rollout-unit value takes precedence when available. Neither is portable total-token usage. See RolloutBudgetConfig for the exact versioned contract.

This typed override is emitted after raw config, and conflicting rollout_budget feature toggles from both this command and its crate::Codex client are suppressed. Codex applies feature toggles after every -c value regardless of argv order, so retaining either toggle would otherwise disable or replace this table.

Source

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

Attach an image to the prompt (--image <path>).

May be called multiple times to attach several images.

Source

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

Set the model to use (--model <model>).

Panics if model is an empty string.

Source

pub fn oss(self) -> Self

Use the OSS model tier (--oss).

Source

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

Use a local model provider (--local-provider <provider>).

Source

pub fn sandbox(self, sandbox: SandboxMode) -> Self

Set the sandbox policy (--sandbox <mode>).

Source

pub fn strict_config(self) -> Self

Error on unrecognized config keys (--strict-config).

Source

pub fn ignore_user_config(self) -> Self

Ignore the user-level config file (--ignore-user-config).

Source

pub fn ignore_rules(self) -> Self

Ignore project rules files (--ignore-rules).

Source

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

Select a named configuration profile (--profile <name>).

Source

pub fn full_auto(self) -> Self

Run in full-auto mode, emitted as --sandbox workspace-write.

--full-auto is deprecated upstream. codex-cli 0.145.0 hides it from codex exec --help and warns when it is used:

warning: `--full-auto` is deprecated; use `--sandbox workspace-write` instead.

This method emits the replacement the CLI names. An explicit sandbox call is more specific and wins over it.

Source

pub fn approve_for_me(self) -> Self

Route approval requests through automatic review, using the workspace-write sandbox (--approve-for-me).

Added in codex-cli 0.147.0. Older releases reject it as an unexpected argument, so this is the one builder method with a floor above the wrapper’s tested minimum. codex exec review and codex exec resume do not accept it.

Source

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

Change the working directory before running (--cd <dir>).

Source

pub fn skip_git_repo_check(self) -> Self

Skip the git repository check (--skip-git-repo-check).

Source

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

Add an extra directory to the context (--add-dir <dir>).

May be called multiple times.

Source

pub fn ephemeral(self) -> Self

Run in ephemeral mode — no session is persisted (--ephemeral).

Source

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

Require output to conform to a JSON schema (--output-schema <path>).

Source

pub fn color(self, color: Color) -> Self

Control terminal color output (--color <mode>).

Source

pub fn json(self) -> Self

Emit JSON Lines output (--json).

When set, stdout will contain one JSON object per line. Use execute_json_lines to parse the events automatically (requires the json feature).

Source

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

Write the last assistant message to a file (--output-last-message <path>).

Source

pub fn retry(self, policy: RetryPolicy) -> Self

Override the retry policy for this command.

Takes precedence over the client-level policy set on Codex.

Source

pub async fn stream<F>(&self, codex: &Codex, handler: F) -> Result<()>
where F: FnMut(JsonLineEvent),

Stream JSONL events from the command, invoking handler for each parsed JsonLineEvent as it arrives.

Automatically appends --json if not already set. Requires the json feature.

§Example

use codex_wrapper::{Codex, ExecCommand, JsonLineEvent};

let codex = Codex::builder().build()?;
ExecCommand::new("what is 2+2?")
    .ephemeral()
    .stream(&codex, |event: JsonLineEvent| {
        println!("{}: {:?}", event.event_type, event.extra);
    })
    .await?;

Source

pub async fn execute_cancellable<C>( &self, codex: &Codex, cancel: C, ) -> Result<CommandOutput>
where C: Future<Output = ()> + Send,

Execute with an explicit cancellation signal.

When cancel resolves, the wrapper terminates the owned process group, awaits the direct child, and then returns Error::Cancelled. The client timeout uses the same settled cleanup path. Retry does not apply to cancellable execution.

Source

pub async fn execute_json_lines( &self, codex: &Codex, ) -> Result<Vec<JsonLineEvent>>

Execute the command and parse the output as JSON Lines events.

Automatically appends --json if not already set. Requires the json feature.

Source

pub async fn execute_json_lines_cancellable<C>( &self, codex: &Codex, cancel: C, ) -> Result<Vec<JsonLineEvent>>
where C: Future<Output = ()> + Send,

Execute cancellably and parse the output as JSON Lines events.

Automatically appends --json if not already set. Process cleanup is complete before a cancellation or timeout error is returned.

Source

pub async fn execute_json(&self, codex: &Codex) -> Result<QueryResult>

Execute the command and return a typed QueryResult.

Assembles the final result text, ids, and token usage from the JSONL event stream. Use execute_json_lines for the raw event stream. Requires the json feature.

Source