# `CodexWrapper`
[🔗](https://github.com/genagent/codex_wrapper_ex/blob/v0.5.3/lib/codex_wrapper.ex#L1)

Elixir wrapper for the Codex CLI.

Provides a typed interface for executing commands against the `codex` CLI.

## Quick start

    # Simple one-shot exec
    {:ok, result} = CodexWrapper.exec("fix the failing test", working_dir: "/path/to/project")

    # Full control via Exec builder
    config = CodexWrapper.Config.new(working_dir: "/path/to/project")

    CodexWrapper.Exec.new("implement the feature")
    |> CodexWrapper.Exec.model("o3")
    |> CodexWrapper.Exec.sandbox(:danger_full_access)
    |> CodexWrapper.Exec.execute(config)

## Binary discovery

The `codex` binary is found via (in order):
1. `:binary` option passed directly
2. `CODEX_CLI` environment variable
3. System PATH lookup

# `completion`

```elixir
@spec completion(CodexWrapper.Commands.Completion.shell(), keyword()) ::
  {:ok, String.t()} | {:error, term()}
```

Generate a shell completion script.

## Examples

    {:ok, script} = CodexWrapper.completion(:zsh)

# `exec`

```elixir
@spec exec(String.t(), keyword()) :: {:ok, CodexWrapper.Result.t()} | {:error, term()}
```

Execute a prompt non-interactively and return the result.

Convenience wrapper that builds a `Config` and `Exec` from keyword options.
Returns `{:ok, %Result{}}` on success or `{:error, reason}` on failure.

## Options

Config options (passed to `CodexWrapper.Config.new/1`):
  * `:binary` - Path to codex binary
  * `:working_dir` - Working directory
  * `:env` - Environment variables
  * `:timeout` - Timeout in ms
  * `:verbose` - Enable verbose output

Exec options (passed to `Exec` builder):
  * `:model` - Model name
  * `:profile` - Named config profile (`--profile`)
  * `:sandbox` - Sandbox mode atom
  * `:approval_policy` - Approval policy atom (`:untrusted`, `:on_request`, `:never`)
  * `:full_auto` - Deprecated; emits `--sandbox workspace-write` (boolean)
  * `:dangerously_bypass_approvals_and_sandbox` - Bypass all (boolean)
  * `:cd` - Working directory for codex subprocess
  * `:skip_git_repo_check` - Skip git check (boolean)
  * `:search` - Web search: `true` (live), `false`, or a mode atom
    (`:cached`, `:indexed`, `:live`, `:disabled`)
  * `:ephemeral` - Ephemeral mode (boolean)
  * `:json` - JSON output (boolean)
  * `:output_schema` - Output schema path
  * `:output_last_message` - Output last message path

## Examples

    CodexWrapper.exec("fix the tests")
    CodexWrapper.exec("implement the feature", working_dir: "/path/to/repo", model: "o3")

# `exec_json`

```elixir
@spec exec_json(String.t(), keyword()) ::
  {:ok, [CodexWrapper.JsonLineEvent.t()]} | {:error, term()}
```

Execute a prompt with `--json` and return parsed NDJSON events.

See `exec/2` for available options.

## Examples

    {:ok, events} = CodexWrapper.exec_json("fix the tests")

# `raw`

```elixir
@spec raw([String.t()], keyword()) :: {:ok, String.t()} | {:error, term()}
```

Run an arbitrary CLI command that isn't wrapped by a dedicated module.

This is the escape hatch for new or experimental CLI subcommands.

## Examples

    CodexWrapper.raw(["version"])
    CodexWrapper.raw(["exec", "fix the tests"], working_dir: "/tmp")

# `review`

```elixir
@spec review(keyword()) :: {:ok, CodexWrapper.Result.t()} | {:error, term()}
```

Run a code review via `codex exec review`.

Convenience wrapper that builds a `Config` and `Review` from keyword options.
Returns `{:ok, %Result{}}` on success or `{:error, reason}` on failure.

## Options

Config options (passed to `CodexWrapper.Config.new/1`):
  * `:binary` - Path to codex binary
  * `:working_dir` - Working directory
  * `:env` - Environment variables
  * `:timeout` - Timeout in ms
  * `:verbose` - Enable verbose output

Review options (passed to `Review` builder):
  * `:prompt` - Additional review context
  * `:uncommitted` - Review uncommitted changes (boolean)
  * `:base` - Compare against base branch
  * `:commit` - Review a specific commit
  * `:title` - PR/review title
  * `:model` - Model name
  * `:full_auto` - Deprecated; emits `--sandbox workspace-write` (boolean)
  * `:dangerously_bypass_approvals_and_sandbox` - Bypass all (boolean)
  * `:skip_git_repo_check` - Skip git check (boolean)
  * `:ephemeral` - Ephemeral mode (boolean)
  * `:output_schema` - Output schema path
  * `:json` - JSON output (boolean)
  * `:output_last_message` - Output last message path

## Examples

    CodexWrapper.review(uncommitted: true, working_dir: "/path/to/repo")
    CodexWrapper.review(base: "main", model: "o3")

# `stream`

```elixir
@spec stream(String.t(), keyword()) :: Enumerable.t()
```

Execute a prompt and return a lazy stream of `%JsonLineEvent{}`.

See `exec/2` for available options.

## Examples

    CodexWrapper.stream("fix the tests")
    |> Enum.each(fn event -> IO.inspect(event.event_type) end)

# `version`

```elixir
@spec version(keyword()) ::
  {:ok, %{version: String.t(), raw: String.t()}} | {:error, term()}
```

Get the Codex CLI version.

## Examples

    {:ok, %{version: "codex 0.1.0", raw: "codex 0.1.0"}} = CodexWrapper.version()

---

*Consult [api-reference.md](api-reference.md) for complete listing*