Direct answer
Codex CLI is OpenAI's terminal coding agent for inspecting repositories, editing files, running commands, and automating development work. Install it with OpenAI's platform installer, npm, or Homebrew. Run codex inside the project you want it to inspect, sign in, keep permissions proportional to the task, and review every resulting command and diff.
What is Codex CLI?
Codex CLI is OpenAI's command-line interface for coding-agent work in a local repository. The interactive codex command opens a terminal conversation where Codex can inspect files, propose and make edits, run approved commands, and explain the result. The separate codex exec command supports non-interactive automation.
The CLI is one Codex surface. OpenAI also provides an IDE extension, desktop app, and cloud workflows. Use the CLI when the repository and development tools are on the machine where the terminal runs.
From installation to a reviewed change
A safe first run moves from installation and sign-in through project selection, permissions, one bounded task, and review.
- Install: Choose one supported installation method.
- Sign in: Use ChatGPT or an API key according to the account and billing path.
- Choose project: Run Codex from the repository it should inspect.
- Set permissions: Keep approvals and sandbox access proportional to the task.
- Run one task: Name a bounded outcome and its verification.
- Review: Inspect commands, changed files, checks, and the final diff.
Prerequisites before installation
- Use a supported macOS, Linux, or Windows environment with a terminal you can identify and control.
- Install Git and put the target project in version control before an agent edits it.
- Have a ChatGPT account or an OpenAI API key for the sign-in method you plan to use.
- Use Node.js only when you choose the npm installation. Use Homebrew only when it already manages packages on the Mac.
- Confirm which repository and directory Codex may inspect. Do not launch it from a broad parent directory by accident.
Install Codex CLI on macOS or Linux
Choose one installation method and use the same method for updates. The official installer is the shortest cross-platform path for macOS and Linux. npm fits a machine that already manages global command-line packages with Node.js. Homebrew fits an existing macOS cask workflow.
Review a remote installer before piping it into a shell when your security policy requires that step. Do not install through several package managers because multiple codex executables make version problems harder to diagnose.
# Official installer for macOS and Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Or install globally with npm
npm install -g @openai/codex
# Or use the Homebrew cask on macOS
brew install --cask codex
# Verify the executable
codex --versionInstall Codex CLI on Windows
OpenAI documents a native PowerShell installer for Windows. Open the current official page first, confirm the command, and run it in a PowerShell session with the permissions required by your organization.
Current Codex releases include Windows-specific sandbox support. A guide that says WSL is always required may describe an older release, although WSL can still be the right environment for a Linux-based project.
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --versionSign in and choose a project
Run Codex from the repository it should inspect. ChatGPT sign-in uses a browser authorization flow. API-key sign-in uses usage-based API access. The chosen method affects the available workspace, billing, retention, and cloud features.
Keep API keys out of shell history, committed files, logs, screenshots, and issue comments. If the key is already in a protected environment variable, pass it to the login command through standard input.
cd /path/to/your/repository
# ChatGPT sign-in
codex login
codex login status
# API-key sign-in from an existing protected environment variable
printenv OPENAI_API_KEY | codex login --with-api-key
# Start the interactive CLI in this repository
codexEssential Codex CLI commands
Start the interactive terminal interface
Confirm the current directory and requested task
Run a non-interactive task in a script or pipeline
Pin inputs, permissions, output, and failure handling
Ask Codex to review a local change
Treat findings as review input, not automatic approval
Continue a previous interactive session
Verify the session and repository before new edits
List configured MCP servers
A listed server does not prove every action is authorized
Collect installation and runtime diagnostics
Remove credentials and private data before sharing output
Configuration and permissions
Codex reads user configuration from ~/.codex/config.toml. Trusted projects can also supply project-scoped configuration in .codex/config.toml. Keep shared project settings reviewable and keep personal credentials outside the repository.
The -C option selects a working directory. Sandbox and approval options control which files and commands Codex can reach and when it must stop for a decision. Start narrow, expand access only for a verified need, and avoid bypass modes outside an independently hardened environment.
# Start in one explicit project
codex -C /path/to/your/repository
# Inspect without write access
codex --sandbox read-only
# Allow project writes and ask before higher-risk actions
codex --sandbox workspace-write --ask-for-approval on-requestAdd MCP to Codex and connect Better Design
MCP lets Codex use tools and context from a configured server. Codex supports commands to add, list, inspect, remove, and authenticate MCP servers. Read the server's source and permissions before you connect it.
Run the Better Design installer first. It detects Codex and updates its MCP configuration without replacing other servers. Use the direct Codex command below only when you need to manage the bearer-token environment variable yourself. The dedicated install page also provides the current config.toml block.
npx better-design
# Manual fallback
codex mcp add better-design \
--url https://better-design.com/api/mcp \
--bearer-token-env-var BETTER_DESIGN_API_KEY
codex mcp get better-design
codex mcp listUse Codex CLI skills and project instructions
A Codex skill packages instructions, references, scripts, or assets for a repeatable task. Project instructions define durable repository rules. Use a skill for a focused method and project instructions for boundaries that should apply to every relevant task.
For interface work, point Codex to the current components, semantic tokens, icons, accessibility rules, and browser verification path. Better Design can add focused design and review guidance through MCP; it does not replace the repository's source of truth.
- Read a skill before trusting its scripts or external services.
- Keep project instructions short, scoped, and close to the files they govern.
- Name the required type check, lint, tests, build, and manual flow.
- Review generated commands and diffs even when the skill is familiar.
Run a first bounded task
Start with explanation before mutation. Ask Codex to identify the application entry point, test command, and one relevant module. Then authorize one observable outcome with a verification command and an explicit boundary.
Read this repository and explain the application entry point, test command, and authentication module. Do not edit files yet. Then propose the smallest change that fixes the failing login redirect test. Keep database and billing code unchanged. After approval, implement it, run the focused test and TypeScript check, and summarize the diff.Troubleshoot Codex CLI installation and setup
- If codex is not found, open a new terminal, inspect the active PATH, and run which codex on macOS or Linux or Get-Command codex in PowerShell.
- If the version is unexpected, identify every installed codex executable and update with the same installer or package manager that created the active one.
- If sign-in fails, run codex login status, confirm the account and billing path, then retry the documented login flow without sharing credential files.
- If Codex opens the wrong repository, exit and restart with codex -C followed by the exact project path.
- If a command is blocked, read the approval and sandbox message before widening access. Do not jump directly to a bypass mode.
- If an MCP server is missing, run codex mcp list and codex mcp get followed by the server name. Confirm the URL and credential source without printing the token.
- If diagnosis is still unclear, run codex doctor and remove secrets or private repository content before sharing the report.
Choose the next Codex setup page
Stay in this guide for Codex CLI installation, authentication, commands, configuration, skills, permissions, MCP, and troubleshooting. Open the Codex MCP install page when Codex already works and you only need to connect Better Design.
Steal this workflow
Run this guide in your own assistant. The prompt carries the guide link and the workflow summary, so the assistant can adapt it to your project.
Read the guide "Codex CLI: install, configure, and use OpenAI Codex" at https://better-design.com/guides/codex-cli and help me apply it to my project.
Codex CLI is OpenAI's terminal coding agent for inspecting repositories, editing files, running commands, and automating development work. Install it with OpenAI's platform installer, npm, or Homebrew. Run codex inside the project you want it to inspect, sign in, keep permissions proportional to the task, and review every resulting command and diff.
Start by asking what I am building and which tools I use. Then walk me through the workflow step by step, adapted to my answers.Claude and ChatGPT open with the prompt filled in. Gemini copies the prompt to your clipboard first, so paste it when the app opens.
Questions
What is Codex CLI?
Codex CLI is OpenAI's terminal coding agent. It can inspect a local repository, edit files, run approved commands, explain code, review changes, and support scripted work through codex exec.
How do I install Codex CLI?
Use OpenAI's current installer for macOS, Linux, or Windows, or install @openai/codex with npm. Homebrew users on macOS can install the codex cask. Choose one method and verify it with codex --version.
Can I install Codex CLI with Homebrew?
Yes. OpenAI documents brew install --cask codex. Use brew upgrade --cask codex for later updates when Homebrew owns the installation.
Do I need an OpenAI API key for Codex CLI?
Not for every local workflow. Codex supports ChatGPT sign-in and API-key sign-in. The selected method affects billing, workspace controls, retention, and some cloud features.
Where is the Codex CLI configuration file?
The default user configuration is ~/.codex/config.toml. Trusted repositories can also use project-scoped .codex/config.toml files for settings that belong to that project.
How do I add MCP to Codex?
Use codex mcp add with a server name and either a remote URL or local command. Then run codex mcp get and codex mcp list to inspect the configuration. Use codex mcp login when the server supports an OAuth flow.
Can Codex CLI use skills?
Yes. Codex skills package focused instructions and optional references, scripts, or assets. Read a skill before use and keep repository-wide rules in project instructions rather than repeating them in every prompt.
Official Codex CLI documentation
Current OpenAI documentation for installation, authentication, commands, configuration, MCP, skills, and the open-source Codex repository.