Exec command -- the primary interface for non-interactive prompts.
Wraps codex exec <prompt> with the full set of CLI flags.
Usage
config = CodexWrapper.Config.new(working_dir: "/path/to/project")
# Build an exec command
exec = CodexWrapper.Exec.new("Fix the failing test")
|> CodexWrapper.Exec.model("o3")
|> CodexWrapper.Exec.sandbox(:workspace_write)
|> CodexWrapper.Exec.ephemeral()
# Execute (returns result)
{:ok, result} = CodexWrapper.Exec.execute(exec, config)Summary
Functions
Add a directory for context.
Set the approval policy.
Set the working directory for the codex subprocess.
Set the color mode: :always, :never, or :auto.
Add a config override (key=value).
Bypass all approvals and sandbox. Use with extreme caution.
Run enabled hooks without requiring persisted hook trust. Use with extreme caution.
Disable a feature.
Enable a feature.
Enable ephemeral mode (no session persistence).
Execute the command synchronously, returning a parsed %Result{}.
Execute the command with --json and return a list of parsed %JsonLineEvent{}.
Enable full-auto mode.
Do not load user or project execpolicy .rules files.
Do not load $CODEX_HOME/config.toml.
Add an image path.
Enable JSON output.
Select which local provider to use ("lmstudio" or "ollama").
Set the model.
Create a new exec command with the given prompt.
Use an open-source provider instead of the default.
Set the output-last-message path.
Set the output schema path.
Select a named config profile.
Set the sandbox mode.
Enable live web search.
Set the web search mode.
Skip the git repo check.
Execute the command and return a lazy Stream of %JsonLineEvent{}.
Error out when config.toml contains fields this Codex version does not recognize.
Types
@type approval_policy() :: :untrusted | :on_request | :never
@type color_mode() :: :always | :never | :auto
@type sandbox_mode() :: :read_only | :workspace_write | :danger_full_access
@type t() :: %CodexWrapper.Exec{ add_dirs: [String.t()], approval_policy: approval_policy() | nil, cd: String.t() | nil, color: color_mode() | nil, config_overrides: [String.t()], dangerously_bypass_approvals_and_sandbox: boolean(), dangerously_bypass_hook_trust: boolean(), disabled_features: [String.t()], enabled_features: [String.t()], ephemeral: boolean(), full_auto: boolean(), ignore_rules: boolean(), ignore_user_config: boolean(), images: [String.t()], json: boolean(), local_provider: String.t() | nil, model: String.t() | nil, oss: boolean(), output_last_message: String.t() | nil, output_schema: String.t() | nil, profile: String.t() | nil, prompt: String.t(), sandbox: sandbox_mode() | nil, search: web_search_mode() | nil, skip_git_repo_check: boolean(), strict_config: boolean() }
@type web_search_mode() :: :cached | :indexed | :live | :disabled
Functions
Add a directory for context.
@spec approval_policy(t(), approval_policy()) :: t()
Set the approval policy.
One of :untrusted, :on_request, or :never. Emitted as the
-c approval_policy="<value>" config override: codex-cli 0.14x removed
the --ask-for-approval flag from exec, and the config key is the
supported equivalent.
:on_failure was accepted by the old flag and is no longer a valid
policy; passing it raises.
Set the working directory for the codex subprocess.
@spec color(t(), color_mode()) :: t()
Set the color mode: :always, :never, or :auto.
The CLI defaults to :auto, which already suppresses color when stdout
is not a terminal. :never is worth setting explicitly when the output
is parsed.
Add a config override (key=value).
Bypass all approvals and sandbox. Use with extreme caution.
Run enabled hooks without requiring persisted hook trust. Use with extreme caution.
Hook trust is what stops a repository from running arbitrary commands the user never approved. Only appropriate for automation that already vets where its hooks come from.
Disable a feature.
Enable a feature.
Enable ephemeral mode (no session persistence).
@spec execute(t(), CodexWrapper.Config.t()) :: {:ok, CodexWrapper.Result.t()} | {:error, term()}
Execute the command synchronously, returning a parsed %Result{}.
@spec execute_json(t(), CodexWrapper.Config.t()) :: {:ok, [CodexWrapper.JsonLineEvent.t()]} | {:error, term()}
Execute the command with --json and return a list of parsed %JsonLineEvent{}.
Forces --json on the exec command, runs synchronously, then parses
each NDJSON line from stdout.
Enable full-auto mode.
Deprecated upstream. Emits --sandbox workspace-write, which is what
the Codex CLI now tells you to use in place of --full-auto. An
explicit sandbox/2 call is more specific and wins over this.
Do not load user or project execpolicy .rules files.
Do not load $CODEX_HOME/config.toml.
Auth still resolves through CODEX_HOME; only the config file is
skipped. Pair with config/2 overrides for a run that does not pick up
the developer's personal settings.
Add an image path.
Enable JSON output.
Select which local provider to use ("lmstudio" or "ollama").
Meaningful alongside oss/1; without it the CLI uses the config
default or prompts for a selection.
Set the model.
Create a new exec command with the given prompt.
Use an open-source provider instead of the default.
Set the output-last-message path.
Set the output schema path.
Select a named config profile.
Emits --profile <name>, which tells the Codex CLI to load the
[profiles.<name>] section of config.toml.
@spec sandbox(t(), sandbox_mode()) :: t()
Set the sandbox mode.
Enable live web search.
Shorthand for search(exec, :live).
@spec search(t(), web_search_mode()) :: t()
Set the web search mode.
One of :cached, :indexed, :live, or :disabled. Emitted as the
-c web_search="<mode>" config override: codex-cli 0.14x removed the
--search flag from exec, and the config key is the supported
equivalent. :live is what --search used to mean.
Skip the git repo check.
@spec stream(t(), CodexWrapper.Config.t()) :: Enumerable.t()
Execute the command and return a lazy Stream of %JsonLineEvent{}.
Reads NDJSON output line-by-line through the configured
CodexWrapper.Runner. The process starts when the stream is consumed
and is terminated when the stream halts. Lines that do not parse as
JSON are skipped.
Forces --json on the exec command.
Error out when config.toml contains fields this Codex version does not recognize.
Turns a silently-ignored typo in a config file into a failed run, which is usually what a programmatic caller wants.