Getting Started with Codex CLI

Codex CLI is OpenAI's open-source command-line coding agent. Unlike ChatGPT (which runs in a browser), Codex CLI operates directly in your terminal with full access to your local file system. It can read your code, write files, and execute shell commands — all under your supervision.

Key characteristics:

Why use a terminal-based AI tool?

• Zero context-switching — stay in your terminal workflow
• Full project awareness — Codex sees your entire codebase
• Direct execution — changes are applied to your real files
• Version control integration — works alongside git naturally
• Scriptable — can be integrated into automated pipelines
• Multi-provider support — works with OpenAI models and compatible APIs

Let's start Codex CLI for the first time. Open your terminal and navigate to a project directory.

# Navigate to your project
cd ~/projects/my-test-project

# Launch Codex CLI in interactive mode
codex

# Navigate to your project
cd ~/projects/my-test-project

# Launch Codex CLI in interactive mode
codex

What you see on launch:

The Codex CLI interface displays:

1. Model indicator — which AI model is being used (default: gpt-5.5)
2. Working directory — confirms the folder Codex is operating in
3. Approval policy — shows the current safety level (default: untrusted)
4. Input prompt — where you type your natural language instructions

Your first interaction:

Type a simple request to see Codex in action:

> List all files in this project and describe the structure

Codex will analyze your directory and provide a summary without making any changes. This is a read-only operation, so no approval is needed.

The approval flow is the core safety mechanism in Codex CLI. When Codex wants to make a change (edit a file, run a command), it shows you exactly what it plans to do and waits for your approval.

The approval cycle:

1. You give Codex an instruction
2. Codex proposes an action (file edit or shell command)
3. You see a preview of the proposed change
4. You choose: approve, reject, or edit

Try it — ask Codex to create a file:

> Create a file called hello.py that prints "Hello from Codex"

Codex will show you the proposed file content:

╭─ Creating file: hello.py ─────────────────────╮
│                                                │
│  print("Hello from Codex")                     │
│                                                │
╰────────────────────────────────────────────────╯

[a]pprove  [r]eject  [e]dit

Your options:

• a (approve) — Codex creates the file exactly as shown
• r (reject) — Codex discards the proposal and you can give new instructions
• e (edit) — You can modify the proposed content before approving

Understanding the diff view:

For file edits (not new files), Codex shows a diff:

  def greet(name):
-     print(f"Hi {name}")
+     print(f"Hello, {name}! Welcome.")
      return name

Lines with - are being removed. Lines with + are being added. Unchanged lines provide context.

Let's run through a complete task to see the full Codex workflow in action. We'll ask Codex to do something slightly more involved.

Task: Create a Python utility function with documentation

> Create a Python file called utils.py with a function that converts
> temperatures between Celsius and Fahrenheit. Include docstrings and
> type hints.

What happens step by step:

1. Codex analyzes your request and determines it needs to create a file
2. It generates the content and presents it for approval:

╭─ Creating file: utils.py ──────────────────────╮
│                                                 │
│  def celsius_to_fahrenheit(celsius: float)      │
│          -> float:                              │
│      """Convert Celsius to Fahrenheit.          │
│                                                 │
│      Args:                                      │
│          celsius: Temperature in Celsius.       │
│                                                 │
│      Returns:                                   │
│          Temperature in Fahrenheit.             │
│      """                                        │
│      return (celsius * 9/5) + 32                │
│                                                 │
│  def fahrenheit_to_celsius(fahrenheit: float)   │
│          -> float:                              │
│      """Convert Fahrenheit to Celsius.          │
│                                                 │
│      Args:                                      │
│          fahrenheit: Temperature in Fahrenheit. │
│                                                 │
│      Returns:                                   │
│          Temperature in Celsius.                │
│      """                                        │
│      return (fahrenheit - 32) * 5/9             │
│                                                 │
╰─────────────────────────────────────────────────╯

[a]pprove  [r]eject  [e]dit

3. Press a to approve
4. Codex creates the file and confirms: Created utils.py

Following up:

You can continue the conversation with follow-up instructions:

> Now add a main block that demonstrates both functions with example values

Codex will propose an edit to the existing utils.py file, showing the additions in diff format.

Beyond natural language prompts, Codex CLI has several built-in commands and keyboard shortcuts for navigation.

Quick command reference:

One-shot mode (non-interactive):

You can also run Codex without entering interactive mode by passing your prompt directly:

# Run a single task and exit
codex "Explain what this project does based on the README"

# Specify a different model
codex --model gpt-5.4 "Add error handling to main.py"

# Run a single task and exit
codex "Explain what this project does based on the README"

# Specify a different model
codex --model gpt-5.4 "Add error handling to main.py"

Quiet mode for scripting:

# Suppress interactive UI, output result to stdout
codex --quiet "What is the main entry point of this project?"

Useful keyboard shortcuts during a session:

• Up/Down arrows — Navigate through prompt history
• Ctrl+C — Cancel current generation or exit
• Ctrl+L — Clear the screen (keeps session active)