Codex CLI

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.

This guide explains how to install Codex CLI on macOS and Arm Linux.

What should I do before installing Codex CLI?

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

Codex CLI requires Node.js 18 or later.

How do I 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.

How do I use npm to install Codex CLI?

The easiest way to install Codex CLI is with npm:

    

        
        
npm install -g @openai/codex

    

Can I use Homebrew to install Codex CLI on macOS?

Yes. Install Homebrew if it’s not already available on your computer.

Install Codex CLI using Homebrew:

    

        
        
brew install --cask codex

    

How do I 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.

What packages do I need before installing Codex CLI on Arm Linux?

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.

How do I install Node.js on Arm Linux?

Codex CLI requires Node.js version 18 or higher. The easiest way to install Node.js on Arm Linux is 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:

    

        
        v22.21.0

        
    

Verify npm is available:

    

        
        
npm --version

    

The output shows the npm version:

    

        
        10.9.4

        
    

How do I 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

    

This downloads and installs the latest version of Codex CLI.

How do I 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:

    

        
        @openai/codex, 0.79.0

        
    

How do I 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 .

How do I 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, refer to the Configuration documentation .

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. This section shows 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. See the Docker install guide for instructions.

How do I 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 /Users/yourname01/yourlocalcodebase with the path to your local codebase.

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

    

        
        
[mcp_servers.arm-mcp]
command = "docker"
args = [
    "run",
    "--rm",
    "-i",
    "-v", "/Users/yourname01/yourlocalcodebase:/workspace",
    "--name", "arm-mcp",
    "armlimited/arm-mcp:latest"
]
startup_timeout_sec = 60

    

How do I 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.

If you’re facing issues or have questions, reach out to mcpserver@arm.com .

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