Walkthrough: Codex CLI: end-to-end

Install the CLI globally so the codex command lands on your PATH. The npm package is @openai/codex; on macOS you can instead use the Homebrew cask or the standalone install script, and on Windows the PowerShell one-liner.

• 1Pick one install path. Use npm if Node is already set up. Homebrew, the curl script, and the PowerShell one-liner are equivalent ways to get the same binary.
• 2The -g flag matters. Installing globally puts codex on your PATH so you can run it from any directory, not just this folder.

🎙Voiceover Start by installing the Codex CLI globally with npm, so the codex command is available from any terminal you open.

Verify the binary resolves before going further. If the shell reports command not found, open a new terminal tab so the updated PATH is picked up, then retry. If you are curious what else the binary can do, run codex --help, the full command menu is captured in the reference screens at the end of this lesson.

• 1Command not found?. Close and reopen the terminal so the updated PATH loads, then run codex --version again.

🎙Voiceover Once that finishes, run codex with the version flag to confirm it installed cleanly and see exactly which build you're on.

Running codex with no arguments starts the interactive terminal UI. The first time you run it there are no stored credentials, so it goes straight to the sign-in screen.

• 1Prefer ChatGPT sign-in. Signing in with your included ChatGPT plan is the recommended path. The API key option is a fallback if you do not have a qualifying plan.
• 2Arrow keys select. Use the arrow keys to highlight an option and press Enter to confirm.

🎙Voiceover Now launch Codex for the first time by simply typing codex, and give it a moment to set itself up.

Codex opens your browser to authenticate via ChatGPT and listens on a local callback URL. Approve the request in the browser, then return to the terminal where the session is now authenticated.

• 1Browser didn't open?. Copy the localhost URL printed in the terminal into any browser on the same machine to finish sign-in.
• 2Re-auth later. You can re-run authentication anytime by starting codex and choosing sign-in again; signing out clears stored credentials. codex login --help (see the reference screens below) lists the status subcommand and the API-key option.

🎙Voiceover Choose Sign in with ChatGPT and press Enter, then complete the login in your browser to connect your account.

Quit back to the shell with Ctrl+C (or open a new tab) and change into the Git repo you want to work in. Codex inspects the current directory to decide its default safety posture, so starting from a clean tree on a feature branch makes review and rollback easy.

• 1Start clean. A clean working tree on a feature branch makes it trivial to see and roll back exactly what Codex changes. A feature branch is a separate line of work you can merge or throw away without touching main.
• 2Tip: point Codex at a folder. You can also target a folder with codex --cd <path> (short form -C) without changing directories first.

🎙Voiceover Change into the repository you want to work in, then run git status so you can see a clean starting point.

Begin in the read-only sandbox so Codex can read files and answer questions but cannot edit anything, run commands, or touch the network without asking. This is the safe way to get oriented in an unfamiliar codebase.

• 1Read-only is safest. In read-only the sandbox blocks edits, command execution, and network access, which is ideal for an unfamiliar or untrusted project.
• 2Check the header. The status line shows the active sandbox and approval mode. Glance at it before every task so you know what Codex is allowed to do.

🎙Voiceover Start Codex in read-only mode here, so it can look around and read your files but can't change anything yet.

Use a plain-English question to map the codebase. Codex reads the relevant files and explains them without changing anything, because the sandbox is read-only. This is a verbatim example prompt from the Codex prompting docs.

• 1Verbatim example. This exact phrasing comes from the official prompting guide. It's a great way to understand code before touching it.
• 2Nothing was written. In read-only mode the answer comes purely from reading files, so your working tree stays untouched.

🎙Voiceover Ask it a plain question, like explaining what a particular module does, to get your bearings before making any edits.

Run the /status slash command to display the session configuration, including the active model, sandbox, approval mode, and which directory is the workspace. Confirm sandbox is read-only and approvals are on-request before you escalate.

• 1Slash commands. Type / to see available commands. /status, /diff, /approvals, and /review are the ones you'll use most in this flow.
• 2Know before you escalate. Confirm the current sandbox and approval mode here before you grant any write access.

🎙Voiceover Type slash status to confirm your current settings, including the model, the sandbox mode, and which approval policy is active.

Restart Codex in workspace-write so it can read, edit files, and run commands inside the working directory automatically, while on-request means it still pauses to ask before editing files outside the workspace, accessing the network, or running anything that escalates out of the sandbox.

• 1This is the 'Auto' preset. The docs describe workspace-write plus on-request as the Auto preset, the recommended default for version-controlled folders.
• 2Switch in-session too. Instead of restarting, you can change sandbox and approval mode live with the /approvals slash command.

🎙Voiceover When you're ready to make changes, restart with workspace-write and on-request approvals, so Codex asks before running anything.

Keep the brief small and verifiable. The core instruction is a verbatim example from the prompting docs; adding a test and a lint run gives Codex a way to check its own work, which the docs say produces higher-quality output. A linter is a tool that automatically checks code for style problems and common errors, so it doubles as a self-check for the agent.

• 1Small and verifiable. Break work into focused steps with a way to verify each one. It's easier for Codex to test and for you to review.
• 2Ask it to plan first. If you're unsure how to scope a task, the docs suggest asking Codex to propose a plan before it starts editing.

🎙Voiceover Give it a small, focused brief: add a json option, write a test for it, and run the linter once you're done.

Because approvals are on-request, Codex pauses and asks before running the linter command. workspace-write lets routine in-workspace commands run automatically, but Codex still asks when it cannot be sure a command stays inside the sandbox, package scripts like npm run lint can spawn arbitrary processes, so it errs on the side of asking. Read exactly what it wants to run, then approve it once, approve and stop asking for the session, or deny it.

• 1Read before approving. Check the exact command before you allow it. Approve only what you understand and expect to run.
• 2Denying is always safe. Choosing "No" stops the command. Codex will adapt or propose a different approach instead of forcing the action.

🎙Voiceover When the approval prompt appears, read what it wants to run, then select Yes and press Enter to run the linter once.

Run the /diff slash command to show the Git diff of everything Codex changed, including files that aren't tracked yet. Treat this exactly like a pull request you are reviewing line by line.

• 1Review like a PR. Read every changed line and run targeted checks before you trust the change, just as you would in code review.
• 2Want a second opinion?. Use the /review command to have Codex review its own working tree and flag issues before you commit.

🎙Voiceover Type slash diff to review every change it made, line by line, before you decide whether to keep any of it.

Ask Codex to run the test you requested. Because approvals are on-request, it pauses again, you approve the command, and you watch the test pass. Verification before committing.

• 1Verify before commit. A passing test plus a reviewed diff is your green light to commit the change.
• 2Approve each run. Every command Codex runs is its own approval, so you stay in control of all side effects.

🎙Voiceover Ask it to run the new test and show you the result, so you can confirm the change actually behaves as intended.

Commit from your own shell so the message and authorship are yours, documenting the change for auditing. You now have a clean checkpoint to build on or roll back to.

• 1Document the decision. A clear commit message records what changed and why, which matters when auditing agent-assisted work.
• 2Full loop complete. Install, sign in, read-only, workspace-write, approve, review, verify, commit. That's the whole safe flow.

🎙Voiceover Finally, commit the reviewed work yourself: stage everything with git add, then commit with a clear message describing the new flag.