CodexWrapper.Config (CodexWrapper v0.7.0)

Copy Markdown View Source

Shared client configuration for the Codex CLI.

Holds binary path, working directory, environment variables, and default options that apply across all commands.

Usage

config = CodexWrapper.Config.new()
config = CodexWrapper.Config.new(working_dir: "/path/to/project")

Summary

Types

t()

Functions

base_args(config)

Build the base command args from config (global flags).

cmd_opts(config)

Build the cmd options (working dir, env) for System.cmd.

find_binary()

Find the codex binary path.

new(opts \\ [])

Create a new config from keyword options.

runner_options(config)

Return validated immutable transport options. Direct structs with nil fields retain legacy application-default lookup; new/1 snapshots those defaults.

stream_opts(config)

Build the runner options for a streaming run.

Types

t()

@type t() :: %CodexWrapper.Config{
  binary: String.t(),
  env: [{String.t(), String.t()}],
  idle_timeout_ms: pos_integer() | nil,
  runner: module() | atom() | nil,
  runner_default_timeout_ms: pos_integer() | nil,
  runner_explicit: boolean() | nil,
  runner_options: keyword() | nil,
  timeout: pos_integer() | nil,
  verbose: boolean(),
  working_dir: String.t() | nil
}

Functions

base_args(config)

@spec base_args(t()) :: [String.t()]

Build the base command args from config (global flags).

Currently always empty. Raises ArgumentError if verbose: true was set on a directly constructed or updated struct.

cmd_opts(config)

@spec cmd_opts(t()) :: keyword()

Build the cmd options (working dir, env) for System.cmd.

find_binary()

@spec find_binary() :: String.t()

Find the codex binary path.

Checks in order:

  1. CODEX_CLI environment variable
  2. System PATH

new(opts \\ [])

@spec new(keyword()) :: t()

Create a new config from keyword options.

Options

  • :binary - Literal executable path or name on PATH (default: auto-discover). Shell commands and unexpanded ~ or environment-variable paths are not supported.
  • :working_dir - Working directory for the subprocess
  • :env - List of {key, value} environment variable tuples
  • :timeout - Whole-command timeout in milliseconds
  • :idle_timeout_ms - Maximum gap between output frames while streaming or using evidenced one-shot execution (default: 300,000 ms)
  • :runner - Runner module or :task / :forcola shorthand. Application defaults are snapshotted at construction, only when this field is absent. An explicitly selected runner must implement stream_lines/4 for streaming; otherwise consumption raises ArgumentError before spawning. Implicit application/default selection retains the legacy Port fallback with a warning. Direct structs with a non-nil runner are treated as explicit selections. :runner_explicit is internal selection provenance set by new/1.
  • :runner_options - Validated one-shot transport options. An explicit [] overrides application defaults. See runner_options/1 for supported keys.
  • :verbose - Compatibility option. Only false is supported; true raises ArgumentError before the CLI is launched, because the Codex CLI does not define a --verbose flag

runner_options(config)

@spec runner_options(t()) :: keyword()

Return validated immutable transport options. Direct structs with nil fields retain legacy application-default lookup; new/1 snapshots those defaults.

Supported keys: :shim_path (absolute path), :env_mode (:inherit or :replace), :timeout_ms, :idle_timeout_ms, :max_output_bytes, :kill_grace_ms, and the paired :interrupt_signal (:int) and :interrupt_grace_ms. Limits are positive 32-bit integers; kill grace may be zero. These requirements need a runner implementing validate_options/1. :timeout_ms supplies the runner default; config :timeout takes precedence. New requirements are refused by unsupported runners before spawning. These options apply to one-shot execution; streams reject nonempty options before spawning rather than silently losing requirements.

stream_opts(config)

@spec stream_opts(t()) :: keyword()

Build the runner options for a streaming run.

Same shape as cmd_opts/1 but with stderr_to_stdout: false: the streaming paths parse NDJSON off stdout, and merging stderr into it would put unparseable lines in the stream. Stderr is left to flow to the parent's stderr.