# CODEX CLI

*Setup Reference Card*

OpenAI's agentic command-line coding tool - Docs: [github.com/openai/codex](http://github.com/openai/codex) <https://developers.openai.com/codex/cli>

Codex CLI is OpenAI’s terminal-based coding agent that reads and edits files, runs commands, and works directly inside your repository. This card covers connecting it to the American Science Cloud’s **Model Access Gateway (MAG)**.

## 1 - Install

Codex is a standalone binary (built in Rust). Install with the platform script or a package manager - pick **one** method per machine.

| **Platform** | **Command** | **Updates** |
|----|----|----|
| macOS / Linux / WSL | curl -fsSL https://chatgpt.com/codex/install.sh \| sh | Re-run script |
| Windows (PowerShell) | irm https://chatgpt.com/codex/install.ps1 \| iex | Re-run script |
| macOS (Homebrew) | brew install --cask codex | brew upgrade |
| Windows (WinGet) | winget install OpenAI.Codex | winget upgrade |

**Also available** (cross-platform, needs Node.js): npm install -g @openai/codex

**Verify the install** - open a new terminal in your project, then:

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<tbody>
<tr>
<td><p>codex --version # confirm the binary is on your PATH</p>
<p>codex # start an interactive session</p>
<p>codex update # Check for and apply an update when the installed release supports self-update</p></td>
</tr>
</tbody>
</table>

|  |
|----|
| **Prerequisite:** You need an AmSC account and a MAG PAT (Personal Access Token) before Codex can reach a model. Set that up in the step below. |

## 2 - Connect to the Model Access Gateway (MAG)

### Step 1 – Get an American Science Cloud (AmSC) Account

Follow the instructions listed here: <https://amsc-docs-d762d2.gitlab.io/GM-getting-started#access--login> to create an AmSC account. Once the account is approved, proceed to the next step.

### Step 2 – Request MAG access and generate a Personal Access Token (PAT)

Follow the instructions listed here: <https://amsc-docs-d762d2.gitlab.io/model-access-gateway#quick-start>

### Step 3 - Set environment variables

Add these to your shell profile (~/.zshrc, ~/.bash_profile, or PowerShell \$PROFILE). Codex reads the OpenAI-style variables.

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<tbody>
<tr>
<td><p># Your MAG project key</p>
<p>export AMSC_I2_API_KEY=&lt;your-MAG-PAT&gt;</p>
<p># Map it to the OpenAI-compatible variables Codex expects</p>
<p>export OPENAI_API_KEY=$AMSC_I2_API_KEY</p>
<p>export OPENAI_BASE_URL=https://i2-api.genesis.american-science-cloud.org/</p></td>
</tr>
</tbody>
</table>

### Step 3 - Verify the variables loaded

Restart your shell (or log out and back in), then check:

|                                                                        |
|------------------------------------------------------------------------|
| env \| grep OPENAI \# OPENAI_API_KEY and OPENAI_BASE_URL should appear |

## 3 - Configure Codex - ~/.codex/config.toml

Codex reserves the built-in provider id openai, so define a **custom** MAG provider and point Codex at it. Create ~/.codex/config.toml:

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<tbody>
<tr>
<td><p>model_provider = "amsc"</p>
<p>[model_providers.amsc]</p>
<p>name = "AmSC Model Access Gateway"</p>
<p>base_url = "https://i2-api.genesis.american-science-cloud.org/v1"</p>
<p>env_key = "OPENAI_API_KEY"</p></td>
</tr>
</tbody>
</table>

## 4 - Start Codex

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<tbody>
<tr>
<td><p>cd my-project</p>
<p>codex # interactive session in this repo</p>
<p>codex "explain the auth flow" # run a one-off prompt</p>
<p>codex -m gpt-5.3-codex # explicitly choose the model for this run</p></td>
</tr>
</tbody>
</table>

## 5 - Everyday Commands

| **Command** | **What it does** |
|----|----|
| codex | Start an interactive session in the current directory |
| codex "..." | Run a one-off prompt, e.g. codex "add tests for utils.py" |
| codex -m \<model\> | Pick a model for this session (e.g. gpt-5.3-codex) |
| codex --profile \<name\> | Load a named config layer (~/.codex/\<name\>.config.toml) |
| codex exec "..." | Non-interactive / scripted run of a single task |
| codex --version | Print the installed Codex version |
| / | (TUI) List in-session slash commands |
| /status | (TUI) Display session configuration and token usage. Note, /usage will not work for API billing via a custom provider like the AmSC Model Access Gateway |

## 6 - Test Your Connection

To confirm that the MAG is correctly configured and answers your requests before starting a long Codex session:

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<tbody>
<tr>
<td><p>curl -s $OPENAI_BASE_URL/v1/chat/completions \</p>
<p>-H "Authorization: Bearer $OPENAI_API_KEY" \</p>
<p>-H "Content-Type: application/json" \</p>
<p>-d '{"model":"gpt-5.3-codex",</p>
<p>"messages":[{"role":"user","content":"Reply with OK."}]}'</p></td>
</tr>
</tbody>
</table>

To sweep every model your key can reach, use the “**[Test all models](https://amsc-docs-d762d2.gitlab.io/model-access-gateway#test-all-available-models)”** script in the MAG docs - it queries /model/info and pings each chat and embedding model.

|  |
|----|
| **Keep secrets out of source.** Never paste a raw key into code, config committed to git, or a shared file. Keep it in an environment variable (or a git-ignored profile) and reference \$OPENAI_API_KEY. |