# Codex CLI

## About this Install Guide

|                                     |                    |
|-------------------------------------|--------------------|
| Reading time:                       | 10 min             |
| Last updated:                       | 4 May 2026         |
| Author:                            | Joe Stech, Arm [GitHub](https://github.com/JoeStech) [LinkedIn](https://linkedin.com/in/joestech) |
| Official docs:                     | [View](https://developers.openai.com/codex/cli/) |

This guide shows you how to install and use the tool with the most common configuration. For advanced options and complete reference information, see the official documentation. Some install guides also include optional next steps to help you explore related workflows or integrations.

Codex CLI is a local, terminal-based coding agent from OpenAI that helps developers explore codebases, generate changes, and run commands using natural language. It’s useful for tasks such as understanding unfamiliar projects, refactoring code, and accelerating development workflows directly from the command line.

Codex CLI supports multiple operating systems, including Arm-based Linux distributions and macOS. By integrating AI assistance directly into command-line workflows, it reduces context switching during development.

In this guide, you’ll learn how to install Codex CLI on macOS and Arm Linux.

## Before you begin

You need an OpenAI account to use Codex CLI. You can either sign in with your [ChatGPT](https://chatgpt.com/) account (Plus, Pro, Team, Edu, or Enterprise plan) or use an OpenAI API key.

Codex CLI requires Node.js 18 or later.

## Download and install Codex CLI

On most systems, install Codex CLI using `npm`. On macOS, there is also the option for you to use Homebrew.

### Use npm to install Codex CLI

To install Codex CLI with `npm`, run:

```
npm install -g @openai/codex
```

### Use Homebrew to install Codex CLI on macOS

Install [Homebrew](https://brew.sh/) if it’s not already available on your computer.

Install Codex CLI using Homebrew:

```
brew install --cask codex
```

## Install Codex CLI on Arm Linux

You can install Codex CLI on Arm Linux distributions using `npm`. This method works on all major Arm Linux distributions including Ubuntu, Debian, CentOS, and others.

### Prerequisites

Before installing Codex CLI, install prerequisite packages and Node.js.

Install the required packages on Ubuntu/Debian systems:

```
sudo apt update && sudo apt install -y curl
```

If you’re not using Ubuntu/Debian, use your package manager to install `curl`.

#### Install Node.js on Arm Linux

Codex CLI requires Node.js version 18 or higher. One way to install Node.js on Arm Linux is by using the NodeSource repository.

Download and run the Node.js setup script. For example, for Node.js 22.x:

```
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
```

Install Node.js:

```
sudo apt install nodejs -y
```

Verify Node.js is installed correctly:

```
node --version
```

The output should show version 18 or higher:

```
__output__ v22.21.0
```

Verify npm is available:

```
npm --version
```

The output shows the npm version:

```
__output__ 10.9.4
```

### Install Codex CLI using npm on Arm Linux

With Node.js installed, install Codex CLI globally using `npm`.

Install Codex CLI globally:

```
sudo npm install -g @openai/codex
```

The command downloads and installs the latest version of Codex CLI.

## Confirm Codex CLI is working

You now have the latest version of Codex CLI installed.

Confirm the CLI is available by printing the version:

```
codex --version
```

The output shows the version:

```
__output__ @openai/codex, 0.122.0
```

## Authenticate with OpenAI

There are two ways to authenticate with Codex CLI.

**Option 1: Sign in with ChatGPT**

Run the `codex` command and select **Sign in with ChatGPT** to authenticate:

```
codex
```

This opens a browser window to complete authentication. This option is recommended if you have a ChatGPT Plus, Pro, Team, Edu, or Enterprise plan.

**Option 2: Use an OpenAI API key**

You can also use an OpenAI API key for authentication. This is useful for developers who prefer API-based access or need to use Codex in automated workflows.

Set the `OPENAI_API_KEY` environment variable:

```
export OPENAI_API_KEY=your-api-key-here
```

Add this command to your shell configuration file (such as ~/.bashrc or ~/.zshrc) to make it permanent.

You can generate an API key from the [OpenAI Platform](https://platform.openai.com/api-keys).

> **Note:** When using an API key, usage is billed to your OpenAI API account rather than being included in your ChatGPT subscription.

## Configure Codex CLI

Codex CLI stores preferences in `~/.codex/config.toml`.

You can configure various options including the default model, approval mode, and MCP servers.

To see all configuration options, see the [Configuration documentation](https://developers.openai.com/codex/cli/reference/).

## Install the Arm MCP server

The Arm MCP Server is an MCP server providing AI assistants with tools and knowledge for Arm architecture development, migration, and optimization. In this section, you’ll learn how to configure the Arm MCP server locally using Docker.

First, pull the MCP server image to your local machine:

```
docker pull armlimited/arm-mcp:latest
```

Ensure Docker is installed and running. For instructions, see the [Docker install guide](https://learn.arm.com/install-guides/docker/).

### Configure the Arm MCP server

Codex CLI uses a TOML configuration file for MCP servers. Modify the file `~/.codex/config.toml` to add the Arm MCP server using Docker.

To analyze a local codebase, use a `-v` argument to mount a volume to the Arm MCP server `/workspace` folder so it can access code you want to analyze with `migrate-ease` and other tools.

Replace the path `/path/to/your/workspace` with the path to your local codebase.

#### Option 1: Edit the Codex configuration file

Add the following to your `~/.codex/config.toml` file:

```
[mcp_servers.arm-mcp]
command = "docker"
args = [
    "run",
    "--rm",
    "-i",
    "--pull=always",
    "-v",
    "/path/to/your/workspace:/workspace",
    "-v",
    "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro",
    "-v",
    "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro",
    "armlimited/arm-mcp:latest"
]
startup_timeout_sec = 60
```

> **Note:** The section must be named `mcp_servers` with an underscore. Using `mcp-servers` or `mcpservers` will cause Codex to ignore the configuration.

#### Option 2: Add from the Codex CLI

You can also add the Arm MCP server from the Codex CLI, after starting `codex` run:

```
codex mcp add arm-mcp -- sh -lc 'docker run --rm -i --pull=always -v "$PWD:/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest'
```

To enable Arm Performix features through the Arm MCP Server, replace `/path/to/your/ssh/private_key` and `/path/to/your/ssh/known_hosts` with the SSH private key and `known_hosts` file used for your target device.

### Optional: Use a Docker replacement containerization tool

You can use other containerization tools besides Docker that are free and don’t require licenses, such as Podman, Finch, Colima, and Rancher Desktop. Choose one of the following options and use its CLI in place of `docker`.

**Install: [Podman](https://podman.io/docs/installation)**

Pull the Arm MCP Server image:

```
podman pull armlimited/arm-mcp:latest
```

Add the following configuration to the user-level `~/.codex/config.toml` file:

```
[mcp_servers.arm-mcp]
command = "podman"
args = [
    "run",
    "--rm",
    "-i",
    "--pull=always",
    "-v",
    "/path/to/your/workspace:/workspace",
    "-v",
    "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro",
    "-v",
    "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro",
    "armlimited/arm-mcp:latest"
]
startup_timeout_sec = 60
```

**Install: [Finch](https://runfinch.com/docs/getting-started/installation/)**

Pull the Arm MCP Server image:

```
finch pull armlimited/arm-mcp:latest
```

Add the following configuration to the user-level `~/.codex/config.toml` file:

```
[mcp_servers.arm-mcp]
command = "finch"
args = [
    "run",
    "--rm",
    "-i",
    "--pull=always",
    "-v",
    "/path/to/your/workspace:/workspace",
    "-v",
    "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro",
    "-v",
    "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro",
    "armlimited/arm-mcp:latest"
]
startup_timeout_sec = 60
```

**Install: [Colima](https://github.com/abiosoft/colima#installation)**

Colima provides a Docker-compatible CLI via Docker contexts.

Pull the Arm MCP Server image:

```
docker pull armlimited/arm-mcp:latest
```

Add the following configuration to the user-level `~/.codex/config.toml` file:

```
[mcp_servers.arm-mcp]
command = "docker"
args = [
    "run",
    "--rm",
    "-i",
    "--pull=always",
    "-v",
    "/path/to/your/workspace:/workspace",
    "-v",
    "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro",
    "-v",
    "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro",
    "armlimited/arm-mcp:latest"
]
startup_timeout_sec = 60
```

**Install: [Rancher Desktop](https://docs.rancherdesktop.io/getting-started/installation/)**

Rancher Desktop uses the Docker container engine via Morby.

Pull the Arm MCP Server image:

```
docker pull armlimited/arm-mcp:latest
```

Add the following configuration to the user-level `~/.codex/config.toml` file:

```
[mcp_servers.arm-mcp]
command = "docker"
args = [
    "run",
    "--rm",
    "-i",
    "--pull=always",
    "-v",
    "/path/to/your/workspace:/workspace",
    "-v",
    "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro",
    "-v",
    "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro",
    "armlimited/arm-mcp:latest"
]
startup_timeout_sec = 60
```

### Verify the Arm MCP server is working

Start Codex CLI and list the tools from the MCP server to verify it is working:

```
codex
```

At the Codex prompt, run the `/mcp` command to view active MCP servers and their status:

```
/mcp
```

The Arm MCP server is listed in the output. If the arm-mcp server indicates it’s still loading, wait a moment and check again.

You can also verify the tools are available by asking Codex to list the available Arm MCP tools.

### Use Arm prompt files with the MCP Server

The Arm MCP Server provides a rich set of tools and knowledge base, but to make the best use of it, you should pair it with Arm-specific prompt files. These prompt files supply task-oriented context, best practices, and structured workflows that guide the agent in using MCP tools more effectively across common Arm development tasks.

#### Get the prompt files

Browse the [agent integrations directory for Codex](https://github.com/arm/mcp/tree/main/agent-integrations/codex) to find prompt files for specific use cases:

- **Arm migration** ([arm-migration.md](https://github.com/arm/mcp/blob/main/agent-integrations/codex/arm-migration.md)): Helps the agent systematically migrate applications from x86 to Arm, including dependency analysis, compatibility checks, and optimization recommendations.

Each prompt file is a Markdown configuration that you can reference in your Codex CLI sessions to enable more targeted, task-specific assistance.

If you’re facing issues or have questions, reach out to [mcpserver@arm.com](mailto:mcpserver@arm.com).

You’re now ready to use Codex CLI with the Arm MCP server for Arm-specific development assistance.