Codex CLI lets you inspect code, edit files, run commands, and connect terminal work to scripts or CI. Because it works directly with local projects and development tools, a successful installation is only the beginning. You also need to verify the signed-in account, working directory, permission boundaries, and the project’s real validation commands.
This guide covers installation and a safe first run. Common commands, configuration files, approval policies, and automation belong in separate articles so the beginner workflow stays focused and maintainable.
Check three things before installing
- Use an official source. Installation commands and supported platforms can change. Copy the command from the current OpenAI Codex CLI page instead of using a third-party download site or an unknown script.
- Prepare a practice project. Do not make your first run inside a directory containing production secrets, customer data, or important files without a backup.
- Keep Git checkpoints. OpenAI’s CLI Quickstart recommends creating Git checkpoints before and after a task so you can inspect and restore changes.
This page was verified on 2026-08-27. If you read it later, compare every command with the official links at the end.
Install Codex CLI on macOS or Linux
OpenAI’s current Codex CLI Quickstart displays this standalone installer for macOS and Linux:
curl -fsSL https://chatgpt.com/codex/install.sh | shThe command downloads a script from an OpenAI domain and passes it to the shell. Treat any download-and-execute command with care: verify the page domain, command, and network environment first. On a managed device, follow your organization’s software-installation policy.
The official page also presents Windows, npm, and Homebrew tabs. Copy their exact commands and platform requirements from the live page on the day you install. This draft does not reproduce options that were not expanded in the verified page view, and it does not guess at Windows steps.
For the standalone route, the current page shows the same installer command for updates. Do not assume every distribution channel updates the same way; follow the instructions for the channel you actually used.
Start Codex from the project directory
After installation, enter the prepared project directory and launch Codex:
cd /path/to/your-project
codexDo not copy the example path literally. Confirm that the terminal is in the intended project and inspect the Git status first. Codex CLI builds its context around the project directory, so starting from the wrong directory can produce irrelevant analysis or unnecessarily broaden file access.
Sign in for the first time
The official Quickstart says that the first codex run lets you choose “Sign in with ChatGPT” or another sign-in method available in the interface. The developer-command reference also documents a dedicated login command:
codex loginWith no flags, the current reference says Codex opens a browser for the ChatGPT OAuth flow. After signing in, check the active authentication mode with:
codex login statusThe official reference also lists API-key and access-token authentication. Pass credentials through secure standard input or a controlled environment. Never put a secret directly into shell history, a project file, a screenshot, an article example, or a Git commit.
Check status and permissions before working
Inside the interactive interface, start with:
/statusThe current command reference says /status reports the active model, approval policy, writable roots, and token usage. A remote connection also shows the remote address and server version. Confirm that:
- the current directory is the project you expected;
- writable locations do not exceed the task’s needs;
- the approval policy matches how you expect commands to run;
- an old configuration has not placed the session in a riskier mode.
The CLI also provides /permissions for choosing what the run may do. Beginners should not bypass approvals or sandboxing before they understand the workflow. The official command reference marks its dangerous bypass option for externally hardened environments, not ordinary local use.
Make the first task read-only
The official Quickstart suggests first tasks such as explaining a project, making a focused change, or helping debug an issue. Begin with a read-only request to verify the directory and context:
Read this project's AGENTS.md, README, and main configuration files. Explain the project's purpose, startup process, and validation commands. Do not modify files, install dependencies, or access anything outside the project directory. List the files you actually inspected and anything you could not verify.Compare the answer with the real files. If Codex cannot find a command, ask it to state that evidence is missing instead of guessing a common command.
Try one focused edit
Once the read-only task is accurate, choose a change that is easy to review:
Goal: Fix one real typo in the README development instructions.
Scope: Change only the README. Do not modify scripts, dependencies, or source code.
Validation: Show the diff. Run the Markdown formatting check if the project has one; otherwise state that no such check ran.
At completion: List changed files, check results, and anything left unverified.Watch the commands and diffs shown in the CLI. If Codex requests network access, software installation, or an additional writable directory, understand why it is needed before approving it.
Review the changes
The current CLI provides /review for checking uncommitted work, a commit, or changes against a base branch. Automated review does not replace reading the diff yourself. In another terminal, inspect Git status and confirm that:
- only expected files changed;
- no earlier user work was overwritten;
- no credentials, logs, caches, or local absolute paths entered the repository;
- test and build results came from real commands;
- checks that did not run are clearly identified.
Common installation and first-run problems
After running codex, the shell says command not found
Review the installation output and confirm whether the installer’s executable directory is on the current shell’s PATH. Open a new terminal and try again. Do not work around a path problem by downloading an unknown binary.
Browser sign-in does not finish
Run codex login again, confirm that the browser opened an official OpenAI or ChatGPT sign-in flow, and check whether the terminal is still waiting for a callback. In a managed or browserless environment, consult the official authentication page for options such as device-code login. Never share a temporary code with another person.
You do not know which authentication method is active
Run codex login status. It prints the active authentication mode. The official reference notes that it exits successfully when credentials are present, which also makes it useful in controlled automation.
Can Codex change every file as soon as it starts?
Its effective access depends on the workspace, sandbox, writable roots, and approval policy. Use /status to inspect the session and /permissions to choose boundaries that fit the task.
Do you need to select a model for the first task?
Do not optimize model selection before confirming the directory, permissions, scope, and validation process. Models and reasoning levels change over time, so rely on the current interface and official documentation instead of an old default quoted in an article.
If you need the product overview first, read What is Codex?. If you prefer a graphical workflow, use the Codex beginner tutorial.
Frequently asked questions
Is Codex CLI the same as the OpenAI API CLI?
No. Codex CLI is designed for agentic code work in the terminal. During installation, make sure you are reading the official Codex CLI documentation, not a page for a different OpenAI command-line tool.
Can I sign in with an API key?
The current developer-command reference documents codex login --with-api-key and requires the key to come from standard input. Check the official authentication and pricing information on the day you use it for current account access, feature availability, and billing conditions.
Does updating Codex CLI modify project files?
Updating the CLI software is separate from editing a project. However, a new version can change commands, behavior, or configuration defaults. Test the updated workflow in a low-risk project before using it for important work.
Should I make my first run in a production repository?
No. Use a practice repository to learn the directory, approval, sandbox, diff, and recovery workflow. Bring the same checks to an important repository only after the process is familiar.
How do I sign out?
The current developer-command reference provides codex logout, which removes saved API-key and ChatGPT authentication credentials. On shared devices, follow your organization’s security rules for local credentials.