Codex CLI on Arch Linux: Setup and First Task

Codex CLI installs on Arch Linux in under five minutes. You install Node.js and npm through pacman, then install the CLI package globally with npm. Arch Linux is a fully supported Linux environment for the tool, and there is nothing Arch-specific in how the CLI runs once it is on your PATH. The setup is the same as on any other Linux distribution that ships a current version of Node.js.

The trickier problem is keeping your project rules and setup notes across sessions. A tool like fenbs stores project instructions and lessons outside any one terminal session, so a fresh shell on the same machine — or a different machine entirely — still picks up where you left off.

What you need before you start

• An Arch Linux system with a working internet connection and sudo access.
• An OpenAI account with API access and an API key from the OpenAI dashboard.
• Node.js 18 or later — the install step below covers this.

Install Node.js on Arch Linux

Arch Linux keeps Node.js in the official repositories. Install it along with npm using pacman:

sudo pacman -S nodejs npm

Check the installed versions once that finishes:

node --version
npm --version

If you need to manage multiple Node.js versions, nvm works on Arch the same way it does on other distributions. The LTS releases are also available as AUR packages (nodejs-lts-iron and similar) if you prefer those. Codex CLI requires Node.js 18 or later.

Install Codex CLI

Install the CLI globally from the OpenAI npm namespace:

npm install -g @openai/codex

Verify the install:

codex --version

If the shell reports command not found, the global npm binary directory is not in your PATH. Find it with npm bin -g and add that path to your ~/.bashrc or ~/.zshrc. For the latest install notes, the OpenAI Codex repository↗ (opens in a new tab) is the primary source.

Authenticate with your API key

Codex CLI reads your API key from the OPENAI_API_KEY environment variable. Export it in your current session:

export OPENAI_API_KEY=your-key-here

To make it persistent, add that line to your ~/.bashrc or ~/.zshrc and reload the shell with source ~/.bashrc. Do not commit the key to a repository or paste it into a shared config file. If your team uses a secrets manager, source the key from there rather than storing a plaintext copy.

Run your first coding task

Change into a project directory and give Codex CLI a small, specific task. A safe first task creates a new file rather than modifying existing code:

cd ~/projects/my-app
codex "write a Python script that prints the current date and time"

The CLI reads your project files, reasons about the task, and shows you a proposed change. You approve or reject each step. For a full list of flags and session options, see codex cli commands.

Choose an approval mode

The default mode asks you to approve each file change. You can adjust this with --approval-mode:

• suggest (default): shows each proposed change and waits for confirmation before writing it.
• auto-edit: applies file edits without asking, but pauses before running any shell command.
• full-auto: applies edits and runs shell commands without prompting. Use only in an isolated sandbox.

For an initial session on a real project, suggest is the safest choice. The codex cli best practices guide covers when raising the automation level makes sense and how to scope tasks so it stays safe.

Save setup lessons so the next session avoids the same problems

The first session on a new machine often surfaces small setup issues: a missing PATH entry, an incompatible Node.js version, or a project-specific init step. If you only fix these in the terminal, the next session discovers the same problems.

Write those findings as Lessons in fenbs. Connect Codex CLI over MCP and ask it to read the project context before starting. It sees the saved lessons and does not repeat the missteps. Shared decision records — like "always run the linter before committing" — work the same way.

How to do this with fenbs

1. Create a free account and add your project. Write a short description and any rules that should apply to every coding session.
2. Connect Codex CLI to fenbs over MCP from Integrations. Sign in with a browser when prompted; no token is pasted into a config file.
3. At the start of each session, ask Codex CLI to read the project context: rules, active tasks, and Where we left off.
4. After a session, ask Codex CLI to record any lessons — such as the PATH fix or the correct install order — and save progress on any tasks it touched.
5. On a reinstall or a different machine, connect to the same fenbs project. The saved rules and lessons are available immediately.

If you prefer to avoid a global npm install, you can run the CLI with npx: npx @openai/codex "your task here". This downloads and runs the current version without installing it permanently, which is useful for trying the tool on a new machine before committing to a global install.

The agent harness topic hub collects more guides on running AI coding tools from the command line, including setup notes for other platforms. The codex-app-vs-cli-vs-ide-extension comparison explains when the CLI is the right choice over the Codex app or IDE plugin.