Codex.CLI (Codex SDK v0.14.0)

Copy Markdown View Source

Thin wrapper around the upstream codex terminal client.

Use this module when you want command-surface parity with the Codex CLI, including commands that do not fit the SDK's structured Codex.Exec or Codex.AppServer APIs.

For long-running or interactive commands, use start/2 or the helpers that return %Codex.CLI.Session{}.

Summary

Types

result()

Functions

app(path_or_opts \\ nil, opts \\ [])

Runs codex app.

app_server(opts \\ [])

Launches codex app-server.

apply(task_id, opts \\ [])

Runs codex apply TASK_ID.

cloud(opts \\ [])

Launches the interactive codex cloud picker.

cloud_exec(query, opts \\ [])

Runs codex cloud exec.

cloud_list(opts \\ [])

Runs codex cloud list.

completion(shell, opts \\ [])

Runs codex completion.

debug_app_server_send_message_v2(message, opts \\ [])

Runs codex debug app-server send-message-v2.

execpolicy_check(command, opts \\ [])

Runs codex execpolicy check.

features_disable(feature, opts \\ [])

Runs codex features disable FEATURE.

features_enable(feature, opts \\ [])

Runs codex features enable FEATURE.

features_list(opts \\ [])

Runs codex features list.

fork(target_or_opts \\ nil, opts \\ [])

Launches codex fork.

interactive(prompt_or_opts \\ nil, opts \\ [])

Launches codex in interactive mode (or one-shot prompt mode when prompt is provided) and returns a raw subprocess session.

login(mode_or_opts \\ :chatgpt, opts \\ [])

Runs codex login.

login_status(opts \\ [])

Runs codex login status.

logout(opts \\ [])

Runs codex logout.

mcp_add(name, arg, opts)

Runs codex mcp add.

mcp_get(name, opts \\ [])

Runs codex mcp get.

mcp_list(opts \\ [])

Runs codex mcp list.

mcp_login(name, opts \\ [])

Runs codex mcp login.

mcp_logout(name, opts \\ [])

Runs codex mcp logout.

mcp_remove(name, opts \\ [])

Runs codex mcp remove.

mcp_server(opts \\ [])

Launches codex mcp-server.

resume(target_or_opts \\ nil, opts \\ [])

Launches codex resume.

run(args, opts \\ [])

Runs a codex command synchronously and collects stdout/stderr until exit.

sandbox(command, opts \\ [])

Runs codex sandbox.

start(args, opts \\ [])

Starts a raw codex subprocess session.

Types

result()

@type result() :: Codex.CLI.Session.result()

Functions

app(path_or_opts \\ nil, opts \\ [])

@spec app(
  String.t() | nil | keyword(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex app.

app_server(opts \\ [])

@spec app_server(keyword()) :: {:ok, Codex.CLI.Session.t()} | {:error, term()}

Launches codex app-server.

apply(task_id, opts \\ [])

@spec apply(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex apply TASK_ID.

cloud(opts \\ [])

@spec cloud(keyword()) :: {:ok, Codex.CLI.Session.t()} | {:error, term()}

Launches the interactive codex cloud picker.

cloud_exec(query, opts \\ [])

@spec cloud_exec(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex cloud exec.

cloud_list(opts \\ [])

@spec cloud_list(keyword()) :: {:ok, result()} | {:error, term()}

Runs codex cloud list.

completion(shell, opts \\ [])

@spec completion(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex completion.

debug_app_server_send_message_v2(message, opts \\ [])

@spec debug_app_server_send_message_v2(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex debug app-server send-message-v2.

execpolicy_check(command, opts \\ [])

@spec execpolicy_check(
  [String.t()] | String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex execpolicy check.

features_disable(feature, opts \\ [])

@spec features_disable(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex features disable FEATURE.

features_enable(feature, opts \\ [])

@spec features_enable(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex features enable FEATURE.

features_list(opts \\ [])

@spec features_list(keyword()) :: {:ok, result()} | {:error, term()}

Runs codex features list.

fork(target_or_opts \\ nil, opts \\ [])

@spec fork(
  String.t() | :last | keyword() | nil,
  keyword()
) :: {:ok, Codex.CLI.Session.t()} | {:error, term()}

Launches codex fork.

interactive(prompt_or_opts \\ nil, opts \\ [])

@spec interactive(
  String.t() | nil | keyword(),
  keyword()
) :: {:ok, Codex.CLI.Session.t()} | {:error, term()}

Launches codex in interactive mode (or one-shot prompt mode when prompt is provided) and returns a raw subprocess session.

login(mode_or_opts \\ :chatgpt, opts \\ [])

@spec login(
  :chatgpt | :device_auth | {:api_key, String.t()} | keyword(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex login.

login_status(opts \\ [])

@spec login_status(keyword()) :: {:ok, result()} | {:error, term()}

Runs codex login status.

logout(opts \\ [])

@spec logout(keyword()) :: {:ok, result()} | {:error, term()}

Runs codex logout.

mcp_add(name, arg, opts)

@spec mcp_add(String.t(), {:command, [String.t()]} | {:url, String.t()}, keyword()) ::
  {:ok, result()} | {:error, term()}

Runs codex mcp add.

mcp_get(name, opts \\ [])

@spec mcp_get(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex mcp get.

mcp_list(opts \\ [])

@spec mcp_list(keyword()) :: {:ok, result()} | {:error, term()}

Runs codex mcp list.

mcp_login(name, opts \\ [])

@spec mcp_login(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex mcp login.

mcp_logout(name, opts \\ [])

@spec mcp_logout(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex mcp logout.

mcp_remove(name, opts \\ [])

@spec mcp_remove(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex mcp remove.

mcp_server(opts \\ [])

@spec mcp_server(keyword()) :: {:ok, Codex.CLI.Session.t()} | {:error, term()}

Launches codex mcp-server.

resume(target_or_opts \\ nil, opts \\ [])

@spec resume(
  String.t() | :last | keyword() | nil,
  keyword()
) :: {:ok, Codex.CLI.Session.t()} | {:error, term()}

Launches codex resume.

run(args, opts \\ [])

@spec run(
  [String.t()],
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs a codex command synchronously and collects stdout/stderr until exit.

sandbox(command, opts \\ [])

@spec sandbox(
  [String.t()] | String.t(),
  keyword()
) :: {:ok, result()} | {:error, term()}

Runs codex sandbox.

start(args, opts \\ [])

@spec start(
  [String.t()],
  keyword()
) :: {:ok, Codex.CLI.Session.t()} | {:error, term()}

Starts a raw codex subprocess session.