By the end of this article, you will have Codex CLI installed on a Mac, authenticated with ChatGPT or an API key, and running a small task inside a Git repository with an approval policy and Seatbelt sandbox you understand.

Prerequisites

You need macOS with an interactive terminal, Git, and either a ChatGPT account that can use Codex or an OpenAI API key. You should know basic shell commands and have a disposable directory where an agent may create files. In this article, the workspace is that disposable project directory. A Git repository is a directory whose files and history are tracked by Git. Codex CLI is an agentic coding tool: it can inspect files, edit them, and run local commands. An approval policy controls when Codex asks before acting; a sandbox is an operating-system boundary that limits what those commands can access. Seatbelt is macOS’s native sandboxing mechanism.

The commands use zsh, the default shell on current macOS releases. See the official Codex CLI quickstart and authentication guide for current options.

Step 1: Install Codex CLI

Install the standalone binary with OpenAI’s installer, then confirm that the codex command is on your PATH, the list of directories your shell searches for executables. The installer can also update an existing installation.

Create the file

No project file is needed yet. Create a workspace for the later commands:

mkdir -p "$HOME/codex-getting-started"
cd "$HOME/codex-getting-started"
touch .keep

Add the code: install-codex.sh

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

Detailed breakdown

  • curl -fsSL downloads the official installer, fails on an HTTP error, and follows redirects.
  • The installer places Codex according to its current user-installation rules.
  • codex --version confirms that the shell can find the executable. The version is intentionally not fixed because releases change.
  • .keep is only a placeholder for this tutorial workspace and is ignored below.

If you use Homebrew, the quickstart also exposes a Homebrew option. Use one installation method so an older binary earlier on PATH does not mask the new one.

Step 2: Authenticate without exposing a secret

Codex CLI supports Sign in with ChatGPT for subscription access and API-key authentication for usage-based access. ChatGPT sign-in opens a browser and completes authentication for the CLI. An API key is a secret credential, so put it in the environment for the current shell or a password manager rather than a repository.

Create the file

Create a local ignore file before adding project files:

mkdir -p "$HOME/codex-getting-started"
touch "$HOME/codex-getting-started/.gitignore"

Add the code: $HOME/codex-getting-started/.gitignore

.DS_Store
.env
*.log
.keep
.codex/

Detailed breakdown

  • .env is ignored because developers often put API keys there. Ignoring it does not secure an already-leaked key.
  • .DS_Store and logs are local artifacts, not source.
  • From the workspace, run codex, choose Sign in with ChatGPT, and finish the browser flow.
  • For an API-key session, run printenv OPENAI_API_KEY | codex login --with-api-key, then run codex. Never include a real key in history, screenshots, or article output.

The authentication method can affect which account policies and data controls apply, so choose deliberately for the work at hand.

Step 3: Start in a Git repository and inspect the session

Codex works against the current directory, so start it from the repository you intend to change. Git gives you a boundary for reviewing changes; create a commit before allowing edits so you have a recovery point. Begin with an explanation-only prompt so you can verify that Codex can read the project.

Create the file

Initialize the disposable repository and add a file for Codex to inspect:

cd "$HOME/codex-getting-started"
git init
touch README.md

Add the code: $HOME/codex-getting-started/README.md

# Codex CLI practice repository

This repository is used to verify a local Codex CLI session.

Detailed breakdown

  • git init creates the repository boundary used for context and diffs.
  • README.md gives the agent a concrete file to summarize.
  • Run codex here, use /status to inspect the active model and directory, then enter Tell me about this project.
  • /permissions shows the active approval and sandbox policy; /model changes the model or reasoning effort when available.

Displayed version, model, and context values vary by release and account. Treat them as session metadata, not fixed output.

Step 4: Make one focused, reviewable change

Ask for a narrow documentation edit only after checking /permissions. This makes the proposed diff easy to inspect and keeps the approval and sandbox policy visible before Codex can change a file.

Create the file

Confirm the repository state before prompting, then create the prompt file that will hold the request:

cd "$HOME/codex-getting-started"
git status --short
touch prompt.txt

Add the code: prompt.txt

Add a one-sentence "Usage" section to README.md explaining that this
repository is a safe place to practice Codex CLI. Show me the proposed diff
before making the edit, then verify the file contents.

Detailed breakdown

  • The request names one file and one small outcome, reducing unintended scope.
  • Asking for the diff makes review part of the task.
  • The verification request asks Codex to inspect the post-edit state, but you should still run git diff yourself.
  • Approve an edit only after checking its path and command.

After the turn, run git diff -- README.md and read the actual working-tree change. A diff is Git’s line-by-line representation of a proposed change.

Step 5: Choose an approval mode and sandbox deliberately

Approval controls when Codex must ask before an action. The sandbox controls what approved commands can access. Keep these concepts separate: a command can be approved yet still constrained by the sandbox. Use /permissions and start with the most restrictive policy that lets the task work.

Create the file

Record choices in a local note, without storing credentials:

cd "$HOME/codex-getting-started"
touch permissions-notes.txt

Add the code: permissions-notes.txt

Interactive practice session
- Start with read-only or approval-required permissions.
- Inspect /permissions before asking for edits or commands.
- Keep the Seatbelt sandbox enabled for local work.
- Review git diff and git status after every change.

Detailed breakdown

  • A read-only or approval-required mode lets you learn the interaction before granting autonomous edits.
  • Seatbelt is macOS’s sandboxing mechanism; Codex uses it to restrict agent-run commands according to the selected policy.
  • A writable workspace can be useful for repository tasks, but it still deserves review.
  • Full access removes important local protections and should be a deliberate choice.

Labels and available modes can change with CLI releases and account policy. Trust the choices shown by /permissions rather than an old screenshot.

Step 6: Demonstrate a complete run and verify the result

After authentication, codex exec runs a non-interactive task suitable for scripts. Use it for a read-only repository inspection, then independently check Git so the article reaches a verifiable result.

Create the file

Create a clean checkpoint before the run:

cd "$HOME/codex-getting-started"
git add README.md .gitignore permissions-notes.txt
git commit -m "Create Codex CLI practice repository"
touch run-codex.sh
git add prompt.txt run-codex.sh
git commit -m "Add Codex CLI practice commands"

Add the code: run-codex.sh

#!/usr/bin/env bash
set -euo pipefail

codex exec "Inspect this Git repository and report its status. Do not edit files, install packages, or run network commands."
git status --short

Detailed breakdown

  • set -euo pipefail stops on errors, unset variables, or failed pipelines.
  • The prompt forbids edits, installation, and network commands, reducing ambiguity.
  • codex exec uses the CLI’s existing authentication, approval, and sandbox settings.
  • The final git status --short is an independent check. A blank result means the tree is clean; any lines require inspection.

Run chmod +x run-codex.sh and then ./run-codex.sh. A successful run prints Codex’s status report and no Git status lines because the files used by the tutorial were committed before the run. Wording, model, and timing vary; the meaningful result is task completion plus the independent Git check. If your installation reports configured MCP authentication warnings before the status report, that is separate from this read-only repository check; inspect or disable those optional integrations if they are not part of your setup.

Troubleshooting

If codex: command not found appears, open a new terminal and run command -v codex. If that returns nothing, inspect the installer output and your shell PATH before installing another copy.

If browser sign-in does not return to the terminal, finish the browser flow and retry codex. For API-key authentication, verify the key is set without printing it: test -n "$OPENAI_API_KEY" && echo "API key is set", then run printenv OPENAI_API_KEY | codex login --with-api-key.

If a command is denied, inspect /permissions and the sandbox explanation. Grant only the capability the task needs. Decline an unexpected path or destructive command and ask for a narrower plan.

Recap

You installed Codex CLI on macOS, authenticated without committing a secret, started it inside Git, prepared a focused change under review, inspected approval and Seatbelt boundaries, and completed a read-only codex exec run. For the next layer, read the configuration guide and the agent instructions guide.