Files

SKILL.mdagents

Install

Install the containing plugin

/plugin install shared-skills@llm-skills

Invoke this skill after installation

/shared-skills:codex-cli

Download codex-cli-skill.zip

This skill is bundled inside shared-skills. Install the plugin once, then Claude Code can use any of its included skills. Browse the full plugin repository at github.com/alisonaquinas/llm-shared-skills.

SKILL.md

name: codex-cli description: "Use this skill when the user wants to install, set up, update, configure, manage, or troubleshoot the OpenAI Codex CLI tool. Triggers: install codex, update codex cli, codex command not found, set OPENAI_API_KEY, configure AGENTS.md, codex auth login, set approval mode, run codex non-interactively, pipe to codex, codex won't start, change the model in codex, or any hands-on operational task with the codex CLI binary. For documentation lookups use codex-cli-docs."

OpenAI Coding CLI

Operational skill for installing, configuring, managing, and troubleshooting the coding CLI binary. For deep documentation lookups, use the companion documentation skill.

Intent Router

Task	Action
Install / first run	See Install below
Update	See Update below
Auth / API key setup	See Auth below
Configure AGENTS.md	See Configuration below
Approval modes	See Approval Modes below
Non-interactive / scripting	See Scripting below
Troubleshooting	See Troubleshooting below
Advanced / docs lookup	Use the companion documentation skill

Install

# npm (global install) — requires Node.js 18+
npm install -g @openai/codex

# Homebrew (macOS/Linux)
brew install codex

First run:

cd your-project
codex "describe what this codebase does"

System requirements: Node.js 18+, macOS/Linux or WSL on Windows.

Update

# npm
npm update -g @openai/codex

# Homebrew
brew upgrade codex

# Check version
codex --version

Release notes: use the companion documentation skill for the changelog URL.

Auth

ChatGPT account (Plus/Pro/Team/Edu/Enterprise)

codex auth login    # opens browser — sign in with OpenAI account
codex auth logout
codex auth status

API key

export OPENAI_API_KEY=sk-...        # set in shell profile for persistence
codex --api-key sk-... "your task"  # pass per-invocation

Store the key in your shell profile to persist across sessions:

echo 'export OPENAI_API_KEY=sk-...' >> ~/.bashrc
source ~/.bashrc

Configuration

AGENTS.md

AGENTS.md at the project root is read at the start of every session. Use it for project-specific instructions, coding conventions, and build commands.

# My Project

## Build & Test
- Build: `npm run build`
- Test: `npm test`

## Conventions
- TypeScript strict mode
- All new functions need JSDoc comments

For the full AGENTS.md spec, use the companion documentation skill.

Config file

Pass a custom config path with --config <path>. For the full config schema, use the companion documentation skill.

Approval Modes

codex "task"                              # suggest (default): proposes, asks before applying
codex --approval-mode auto "task"         # auto-approves safe file edits; prompts for shell commands
codex --approval-mode full-auto "task"    # applies all changes and runs commands without asking

Mode	Safe for	Caution
`suggest`	Any task	Slowest; requires manual approval
`auto`	Trusted projects	Still prompts for shell commands
`full-auto`	CI / trusted automation only	Runs shell commands unattended

Scripting

# Non-interactive run
codex --non-interactive "fix all TypeScript errors"

# Quiet output (suppress progress noise)
codex --quiet "run the tests and report failures"

# Set working directory
codex --cwd /path/to/project "update the README"

# Pipe input
cat error.log | codex "what is causing these errors?"
git diff | codex "review these changes for issues"

# Switch model
codex --model o3 "refactor this module"

Troubleshooting

Symptom	Fix
CLI binary not found	Re-run the install step (see Install); check `$PATH`
`OPENAI_API_KEY not set`	Export the key or authenticate via browser (see Auth)
Auth loop / browser won't open	Sign out then sign in again (see Auth)
Node.js version error	Upgrade to Node.js 18+ (`node --version`)
Slow / no response	Check internet; try `--verbose`
Changes not applying	Check approval mode; ensure `--non-interactive` isn't blocking
Wrong AGENTS.md loaded	Run with `--verbose` to see which config files are loaded
Model not available	Verify your OpenAI plan supports the requested model

Enable verbose logging:

codex --verbose "your task here"

For issues not covered here, use the companion documentation skill to look up the relevant documentation page.