Your Terminal Just Got an AI Engineer: A Complete Beginner's Guide to Codex CLI

5-min read · A hands-on walkthrough for developers who've never used an AI coding agent before
Focus: Beginners · CLI · OpenAI

You know this moment.

You paste code into ChatGPT, ask "find the bug" — and it gives you a brilliant analysis. Then comes the tedious part: manually copying the fix back into your editor, switching windows, testing, repeat. Thirty minutes gone.

It's like having a smart friend who gives great advice but can never touch your keyboard.

Codex CLI is different. It doesn't just give advice. It does the work on your machine.

What is Codex CLI, in one sentence

Codex CLI is OpenAI's open-source terminal AI engineer. You tell it what you need in plain English, and it reads your code, writes files, and runs commands — all on your local machine.

It's not a ChatGPT plugin. It's not an IDE autocomplete. It's a standalone AI assistant that lives in your terminal, with its own interface, its own safety rules, and its own way of working.

Codex CLI vs ChatGPT: Why "doing" beats "talking"

Here's the difference: ChatGPT is a conversation tool. Codex CLI is an execution tool. One gives you suggestions. The other gets things done.

Installation: 3 minutes to your first AI conversation

Step 1: Open your terminal and install

npm install -g @openai/codex

Requires Node.js v22+. macOS users can also use:

brew install --cask codex

Once installed, log in with your OpenAI account:

codex auth

You can use your ChatGPT Plus/Pro subscription (usage counts toward your plan, no extra cost) or an API key. For beginners, the ChatGPT account route is simplest.

Step 2: Launch!

codex

You'll see a full-screen terminal interface (called a TUI — Terminal User Interface). It's not as flashy as the ChatGPT web app, but it's significantly more powerful.

Step 3: Say your first words

Type this directly into the TUI:

Write a Python script that downloads the top 10 posts from Hacker News
and prints their titles with links.

Codex scans your environment, checks that Python is available, creates the script, runs it, and shows you the output. You might need to hit y once to confirm execution.

This is the core Codex CLI experience: you speak → it acts → you confirm → done.

Understanding the TUI: the only shortcuts you need

Beginner tip: For the first week, only use two things — typing directly + /diff to review changes. Add the others gradually.

5 tasks you can use tomorrow at work

Task 1: Explore an unfamiliar codebase

Just joined a project with 50,000 lines of unknown code?

Explain the architecture of this project. What are the main modules,
how do they connect, and where should I start reading?

Codex scans the directory structure, reads key files, and delivers a map. What used to take half a morning of manual code reading now takes 2 minutes.

Efficiency: half a day → 2 minutes

Task 2: Fix a broken CI pipeline

Your CI is red, and you're not sure which test is failing.

codex exec "Check which tests are failing, find the root cause, and fix them"

codex exec (or codex e for short) is non-interactive mode — no TUI, runs the task, returns the result. Perfect for CI/CD pipelines.

Efficiency: manual debugging → one command

Task 3: Add missing documentation

"Nobody documented this codebase, and my manager wants docs."

codex exec "Find all public functions in src/ without docstrings and add them following PEP 257" --sandbox workspace-write

Codex scans for undocumented functions, generates docstrings according to your specification, and runs the linter to verify.

Efficiency: 500-file project from 2 days → 30 minutes

Task 4: Code review before you commit

You've changed several files and want an AI second opinion.

In the TUI, type /review. Codex automatically compares your changes, gives you a risk assessment, and suggests improvements. You can also customize:

/review → Custom review instructions → "Focus on security issues and SQL injection risks"

Task 5: Generate code from screenshots

Your designer sent you a mockup, and you need to build the UI.

codex -i mockup.png "Implement this UI using Tailwind CSS"

Codex "sees" the screenshot, analyzes the layout structure, and generates matching frontend code. Not perfect, but typically saves 70% of the manual implementation time.

Security: why you can trust an AI with your files

Many developers have a visceral discomfort with "letting AI operate my computer." Codex CLI addresses this with three layers of protection:

Layer 1: Approval modes (you decide)

Switch anytime in the TUI with /permissions.

Layer 2: OS-level sandbox (the glass cage)

Codex CLI uses operating system-level sandboxing — not application-layer hooks. On macOS it uses Seatbelt, on Linux it uses bubblewrap, and on Windows it uses native sandboxing. By default, the AI can only touch files in your current directory.

Layer 3: Rule engine (some commands are permanently banned)

Certain commands are never allowed, regardless of what the AI asks: sudo, bash -c, rm -rf / — these are hard-coded into a blocklist. No amount of convincing will execute them.

In short: the AI can be powerful, but it cannot escape.

Three beginner mistakes (and how to avoid them)

Mistake 1: Using Codex CLI like ChatGPT

❌ Wrong: "Explain this code to me" (treating it as a Q&A tool)
✅ Right: "Refactor this module to use async/await" (giving it a task)

Codex CLI is action-oriented. Give it tasks, not questions. Every prompt should imply "please do this."

Mistake 2: Running Full Access for daily development

❌ Dangerous: Beginners jumping straight to full-automatic mode
✅ Safe: Use Auto mode for daily work — let Codex ask before running commands. Full Access only for CI/CD scripts.

Mistake 3: Forgetting /diff

❌ Problem: Unsure what changed after Codex ran a task
✅ Habit: Make /diff your ritual after every Codex session, before you commit

Quick reference card (print and stick on your desk)

From here: your next three steps

1. Install and play — Spend 10 minutes installing, logging in, and running 3 simple commands. Just build muscle memory.
2. Pick one real task — Choose something you'd actually do at work (adding docs, fixing a bug, exploring a project) and let Codex handle it.
3. Make /diff a habit — After every Codex session, review the changes before committing. This builds trust.

Codex CLI isn't replacing you. It's freeing you to spend time on deciding what to build, not how to build it.

References

• OpenAI Codex CLI Official Docs
• Codex CLI GitHub Repository (74.5K+ Stars, Apache 2.0)
• Shareuhack: Complete Guide to Codex CLI
• Codex Knowledge Base: Rust Rewrite Architecture
• IT之家: OpenAI Launches Codex CLI Open-Source Terminal Agent