> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using APIMart in Codex CLI

> A detailed guide on configuring and using APIMart API services in Codex CLI, enabling you to access multiple AI models for assisted programming with simple configuration.

## Introduction

Codex CLI is OpenAI's open-source terminal coding agent that can read and write files, run commands, fix bugs, and complete full coding tasks directly in the command line.
By connecting through APIMart, you can freely use multiple models — including GPT and Claude — in Codex CLI, with more flexible and competitive pricing.

## Prerequisites

Before you begin, make sure you have:

1. **Installed Node.js**
   Download and install from the [Node.js website](https://nodejs.org/) (latest LTS, v20 or newer recommended) to install Codex CLI via npm

2. **Obtained an APIMart API Key**
   Log in to the [APIMart Console](https://apimart.ai/keys) to get your API key (starts with `sk-`)

<Note>**Tip:** If you don't have an APIMart account yet, please register at [APIMart](https://apimart.ai) first and obtain your API key.</Note>

## Step 1: Install Codex CLI

Choose any of the following methods to install:

<Tabs>
  <Tab title="npm (Recommended)">
    Install globally with npm — works on all operating systems:

    ```bash theme={null}
    npm install -g @openai/codex
    ```

    <Note>If you run into permission issues, prepend `sudo` (macOS / Linux).</Note>
  </Tab>

  <Tab title="Homebrew (macOS)">
    macOS users can also install with Homebrew:

    ```bash theme={null}
    brew install codex
    ```
  </Tab>
</Tabs>

### Verify the installation

After installing, run the following command to confirm:

```bash theme={null}
codex --version
```

If a version number is printed, the installation succeeded.

## Step 2: Configure the APIMart API

Codex CLI manages model providers via configuration files under the `~/.codex/` directory. All we need to do is add a custom provider pointing to APIMart.

### 2.1 Locate the config directory

* **macOS / Linux:** `~/.codex/`
* **Windows:** `C:\Users\<username>\.codex\`

<Note>If the directory does not exist, run `codex` once in your terminal then press `Ctrl + C` to exit — it will be created automatically.</Note>

### 2.2 Configure the API key

In the config directory, create or edit the `auth.json` file and fill in your APIMart key:

```json theme={null}
{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxx"
}
```

| Field            | Description                              |
| ---------------- | ---------------------------------------- |
| `OPENAI_API_KEY` | Your APIMart API key (starts with `sk-`) |

### 2.3 Configure the model provider

In the config directory, create or edit the `config.toml` file and add the APIMart provider:

```toml theme={null}
# Default model
model = "gpt-5.5"
# Default provider — matches [model_providers.apimart] below
model_provider = "apimart"

# APIMart provider configuration
[model_providers.apimart]
name = "APIMart"
base_url = "https://api.apimart.ai/v1"
wire_api = "responses"
requires_openai_auth = true
```

| Field                  | Description                                                               |
| ---------------------- | ------------------------------------------------------------------------- |
| `model`                | Default model ID — pick one from the model list below                     |
| `model_provider`       | Default provider — must match the ID inside `[model_providers.xxx]`       |
| `name`                 | Display name of the provider — can be customized                          |
| `base_url`             | APIMart's OpenAI-compatible URL — fixed at `https://api.apimart.ai/v1`    |
| `wire_api`             | Wire protocol — recent Codex versions require `responses` (Responses API) |
| `requires_openai_auth` | Set to `true` to authenticate using the key from `auth.json`              |

After saving both files, restart Codex CLI for the changes to take effect.

<Warning>Make sure `auth.json` is valid JSON and `config.toml` is valid TOML. Do not use full-width / smart quotes, otherwise the config won't apply.</Warning>

## Step 3: Get Started

### Verify the configuration

In any project directory, run the following command to confirm everything is wired up:

```bash theme={null}
codex "Introduce yourself in one sentence"
```

If you get an AI reply, the configuration is working. If you see a sign-in screen, or `401` / `403` errors, refer to the FAQ section below.

### Interactive mode

Run `codex` directly to enter the interactive UI — ideal for full coding tasks:

```bash theme={null}
codex
```

Once inside, describe what you need in natural language, e.g.:

```
Create an Express.js server with a JSON-returning health check endpoint
```

Codex will analyze your project, generate code, run commands, and ask for confirmation before performing sensitive operations.

### Approval modes

On first run, Codex will ask you to pick an approval level:

| Mode            | Description                                                                      |
| --------------- | -------------------------------------------------------------------------------- |
| **Read Only**   | Only file reads are allowed — any modification or command requires confirmation  |
| **Auto**        | Can read/write files and run commands within the working directory (recommended) |
| **Full Access** | Performs any operation without confirmation — use with caution                   |

We recommend starting with **Auto** mode. Type `/approvals` in the interactive UI to change it anytime.

### Switch models

In the interactive UI, type `/model` to switch quickly, or change the `model` field in `config.toml` and restart.

## Supported Models

For Codex CLI, the following GPT-5 series models are recommended:

| Model ID        | Strengths                                  | Recommended Use Cases                     |
| --------------- | ------------------------------------------ | ----------------------------------------- |
| `gpt-5.5`       | Latest flagship, top coding ability        | First pick for Codex, complex engineering |
| `gpt-5.4`       | Previous-generation flagship, very capable | Complex coding, architecture design       |
| `gpt-5.4-mini`  | Lightweight, fast, cost-effective          | Daily coding, fast iteration              |
| `gpt-5.3-codex` | Coding model optimized for Codex           | Agentic coding tasks                      |
| `gpt-5.2`       | Stable and balanced                        | Routine coding tasks                      |

<Tip>
  **Model selection tips:** The GPT-5 series above pairs best with Codex CLI. For the best experience, prefer `gpt-5.5`; `gpt-5.3-codex` is specifically optimized for Codex's agentic coding scenarios.
</Tip>

## Common Commands

Frequently used commands and shortcuts in Codex CLI:

| Command                 | Description                            |
| ----------------------- | -------------------------------------- |
| `codex`                 | Enter the interactive UI               |
| `codex "task"`          | Start with an initial instruction      |
| `codex exec "task"`     | Non-interactive mode — run and exit    |
| `codex --model gpt-5.4` | Start with a specified model           |
| `codex --version`       | Show the version number                |
| `/model`                | Switch model inside the interactive UI |
| `/approvals`            | Adjust approval mode inside the UI     |
| `Ctrl + C`              | Exit the interactive UI                |

## FAQ

### Q1: A ChatGPT sign-in screen appears after launch?

If you see "Sign in with ChatGPT" or similar after launch, the configuration didn't take effect.

**Troubleshooting:**

1. Make sure both `config.toml` and `auth.json` are inside `~/.codex/`
2. Check that `model_provider` in `config.toml` is set to `apimart`
3. Check that `auth.json` is valid JSON and the key is filled in completely

### Q2: Getting 401 / 403 errors?

| Status Code        | Meaning                                | Solution                                                       |
| ------------------ | -------------------------------------- | -------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid API key             | Check the key in `auth.json` — it should start with `sk-`      |
| `403 Forbidden`    | Insufficient permission or expired key | Go to the [Console](https://apimart.ai/keys) to verify the key |

Also make sure `base_url` is set to `https://api.apimart.ai/v1`, not the official OpenAI URL.

### Q3: Connection failed?

1. Check your network connection
2. Make sure `base_url` in `config.toml` is correct
3. If you're behind a proxy, ensure it allows access to `api.apimart.ai`

### Q4: `wire_api = "chat"` is no longer supported?

Recent Codex CLI versions (0.84.0 and later) have removed the `chat` protocol. Update `wire_api` in `config.toml` to `responses`:

```toml theme={null}
wire_api = "responses"
```

APIMart supports the Responses API — just restart Codex after the change.

### Q5: Tool calls or runs are failing?

Make sure `wire_api` in `config.toml` is set to `responses`. If you still hit compatibility issues, switch to a recommended GPT-5 series model (e.g. `gpt-5.5`, `gpt-5.3-codex`) — they pair more reliably with Codex CLI.

### Q6: Use environment variables instead of auth.json?

You can also configure the key via an environment variable. Change the provider block in `config.toml` to:

```toml theme={null}
[model_providers.apimart]
name = "APIMart"
base_url = "https://api.apimart.ai/v1"
wire_api = "responses"
env_key = "APIMART_API_KEY"
```

Then set the environment variable `APIMART_API_KEY` to your APIMart key. `auth.json` is no longer required in this setup.

### Q7: How do I switch models?

Two ways:

1. **In the interactive UI**: Type `/model` to switch
2. **Edit the config**: Change the `model` field in `config.toml` and restart Codex CLI

### Q8: How do I check usage and billing?

Log in to the [APIMart Console](https://apimart.ai/overview) to view API call statistics, token consumption details, and cost trends.

## Support and Help

If you run into any issues while using Codex CLI:

* 📚 [APIMart Documentation Center](https://docs.apimart.ai)
* 💬 [Discord Community](https://discord.gg/V8zqssyZ5c)
* 🐦 [Twitter @APIMart\_](https://x.com/APIMart_)
* 📧 Technical support: [zhihong@apimart.ai](mailto:zhihong@apimart.ai)

***

<Card title="Get Started with APIMart" icon="rocket" href="https://apimart.ai">
  Sign up for APIMart now, get your API key, and experience a multi-model programming assistant in Codex CLI!
</Card>