# Codex CLI + Luma Cloud

Use Luma's Responses API for one CLI session while preserving your normal OpenAI configuration.

API connection: Responses. Instructions checked: 2026-09-28. Client capabilities and versions may vary; follow the verification steps below.

This is an API setup guide. SuperGPT desktop installation and sign-in are separate; use a customer API key for the client described here.

## Before you start

- Create a portable key in Dashboard → API. Use API Wallet credit, or a Builder key when that option is available to your account.

- This is a direct API connection. SuperGPT is not required. Use a named Wallet key on any plan, or a subscription key if your Builder account offers one; your desktop sign-in is not an API key.

- Load LUMA_CLOUD_API_KEY from your secret manager or a private environment before starting the client. Never put the key in a prompt, Git, or a shared configuration file.

- Codex CLI with custom-provider and -c overrides. Check codex --help for your installed version.

## Setup

1. **Choose a Responses model**
   Replace MODEL_ID_FROM_CATALOG with a Responses-capable Luma model and SUPPORTED_EFFORT_FROM_MODEL_DOCS with a reasoning effort that same model supports. The command selects provider, model, and effort together for this run, overriding any saved effort. Chat Completions alone is not enough for current Codex CLI.

2. **Start a separate CLI session**
   Use the command below from your project. Provider settings apply only to this invocation. Do not add them to ~/.codex/config.toml, overwrite your OpenAI provider, log out, or modify ChatGPT/Codex desktop.

3. **Confirm the session**
   Use /status and /debug-config to inspect the active session and configuration layers before the first request. Keep normal sandbox and approval controls enabled. When changing the model, also select an effort supported by the new model. Never use an existing OpenAI conversation as the first compatibility test.

4. **Optional: save a CLI-only named profile**
   Current Codex versions use a separate luma-cli.config.toml beside the user config, selected only with --profile luma-cli. The default location is ~/.codex/luma-cli.config.toml on macOS/Linux and %USERPROFILE%\.codex\luma-cli.config.toml on Windows. If you already use a custom Codex state location, keep it and use its documented profile directory. Create only this named file; do not edit the shared config.toml, auth.json or desktop settings. Codex versions before 0.134.0 use a different profile format: use the one-run command instead of copying this profile into an older format.

## Bash / Zsh — command-scoped provider

```bash
codex \
  --model 'MODEL_ID_FROM_CATALOG' \
  -c 'model_reasoning_effort="SUPPORTED_EFFORT_FROM_MODEL_DOCS"' \
  -c 'model_provider="luma_cloud"' \
  -c 'model_providers.luma_cloud.name="Luma Cloud"' \
  -c 'model_providers.luma_cloud.base_url="https://api.lumaos.cloud/v1"' \
  -c 'model_providers.luma_cloud.env_key="LUMA_CLOUD_API_KEY"' \
  -c 'model_providers.luma_cloud.wire_api="responses"' \
  -c 'model_providers.luma_cloud.requires_openai_auth=false' \
  -c 'model_providers.luma_cloud.supports_websockets=false'
```

First load the key using one of the private input examples below, then replace both model and effort placeholders. No login/logout or persistent provider changes are required. Start Codex without these flags to use your existing defaults again. On Windows, the separate TOML profile below avoids native-command quoting differences.

## macOS / Linux · Bash or Zsh · private key input

```bash
printf 'Luma Cloud API key: ' >&2
read -r -s LUMA_CLOUD_API_KEY
printf '\n' >&2
export LUMA_CLOUD_API_KEY
```

Run in an interactive terminal, paste the key at the hidden prompt and press Enter. The value is available to programs launched from this terminal, not apps already running. Do not enable shell tracing. After closing the client, unset LUMA_CLOUD_API_KEY to remove it from this shell.

## Windows · PowerShell · private key input

```powershell
$lumaSecret = Read-Host 'Luma Cloud API key' -AsSecureString
try {
  $env:LUMA_CLOUD_API_KEY = [System.Net.NetworkCredential]::new('', $lumaSecret).Password
} finally {
  $lumaSecret.Dispose()
  Remove-Variable lumaSecret
}
```

The key becomes a process environment value without being printed or included in the command. Start the client from this PowerShell window. Remove-Item Env:LUMA_CLOUD_API_KEY clears it after you close the client; do not use setx to make the secret global.

## Optional luma-cli.config.toml · Codex 0.134.0 and later

```toml
model = "MODEL_ID_FROM_CATALOG"
model_provider = "luma_cloud"
model_reasoning_effort = "SUPPORTED_EFFORT_FROM_MODEL_DOCS"
web_search = "disabled"

[model_providers.luma_cloud]
name = "Luma Cloud"
base_url = "https://api.lumaos.cloud/v1"
env_key = "LUMA_CLOUD_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
```

This is the whole content of a new dedicated profile, not a replacement for config.toml. Replace model and effort placeholders. Do not wrap these values in [profiles.luma-cli]; current profiles use top-level keys. No API key or OpenAI login is stored in the file.

## Launch the named profile · Bash, Zsh or PowerShell

```sh
codex --version
codex --profile luma-cli --sandbox read-only
```

Run from a disposable project after loading the key. The profile keeps inherited approval settings, while this first session explicitly prevents file writes through the sandbox. Omit --profile luma-cli in a later normal launch to use your existing configuration again.

## Inside the new Codex CLI session

```text
/status
/debug-config
Reply with: Luma connection ready.
```

Inspect the model/provider settings before sending the last line. The last line uses API quota or funds. After it works, ask Codex to read one harmless README and summarize it; approve only the read you expect.

## Verify

- Start a new session with the exact Luma Cloud model selected and ask for a short text reply. This is a billable API request.

- For Wallet keys, check Usage → API Wallet for the matching usage. For Builder keys, check subscription Usage. A model in a picker confirms configuration, not a successful response.

- Confirm a completed read-only file operation in the CLI, then its final answer. If only text succeeds, report chat verified and tools not yet verified. Do not enable web search, remote execution or automatic approvals as a connection workaround.

## Limits

- Current official configuration documents wire_api=responses. Do not use older wire_api=chat examples.

- This setup documents the CLI connection, not desktop integration. Built-in web search, remote execution, images, and other optional features need separate support.

## Troubleshooting

### Luma profile is not found or has no effect

Check the CLI version, exact luma-cli.config.toml filename and --profile luma-cli spelling. Current profile files sit beside user config.toml and contain top-level keys. Project-local .codex/config.toml cannot define the custom provider. Use /debug-config to see which file was loaded, without posting its private contents.

### A browser login opens or the OpenAI provider is active

Stop before sending a request and check model_provider=luma_cloud, env_key=LUMA_CLOUD_API_KEY and requires_openai_auth=false in the selected invocation/profile. Do not log out of OpenAI, delete auth.json or copy a desktop token into the environment to fix this.

### 400 for reasoning effort, or a Responses error

Use a model that supports Responses and an effort value supported by that exact model. Replace the effort placeholder instead of inheriting a setting from another model. A working Chat Completions request does not qualify the Responses route; keep wire_api=responses and confirm the correct Base URL.

### Works in one terminal but not another

The environment secret is scoped to the terminal that launched Codex. Enter it again in the intended shell or load it through your secret manager. The named profile contains only a variable reference; it cannot retrieve an environment value from a different running process.

## Official client documentation

- [OpenAI: custom model providers](https://learn.chatgpt.com/docs/config-file/config-advanced)

- [OpenAI: provider configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)

- [OpenAI: CLI flags and named profiles](https://learn.chatgpt.com/docs/developer-commands)

- [OpenAI: inspect active settings](https://learn.chatgpt.com/docs/developer-settings)