How to Use Codex: A Complete Beginner Guide to the CLI, IDE Extension, Codex Cloud, and Desktop App

When you use Codex for the first time, do not ask it to refactor the whole project. Open the repository first and give it one small task you can verify in about 20 minutes.

Entry Point Overview

OpenAI Codex is not one terminal command or one editor plugin. It is a coding agent that can be used through multiple entry points. In the official documentation you will see the CLI, IDE extension, Codex app, and Codex web/cloud. They share the same underlying capability and authentication model, but they fit different work.

Four Entry Points Compared

Entry point	What it is	Best for	Typical user	Main constraint
CLI	A coding agent running in your local terminal	Existing local repositories, small changes, command-line workflows	Heavy terminal users, CI users	Needs a local Git repository; file changes are visible locally
IDE Extension	Codex collaboration in an editor sidebar	Current editor work, shorter context through open files or selected code	VS Code, Cursor, Windsurf, and JetBrains users	Depends on the editor environment; complex work can be delegated to Cloud
Codex App	A desktop command center	Multiple threads, worktrees, automations, Git management	Local users handling several tasks in parallel	macOS and Windows are supported; Linux availability should be checked on the official page
Codex Cloud/Web	A cloud agent connected to GitHub	Remote repositories, PRs, asynchronous tasks, work away from your machine	Team users and remote-repository workflows	Enterprise workspaces may require admin setup

Authentication and Feature Differences

Codex supports two authentication paths, but the available features are different:

Authentication	Available entry points	Cloud feature availability	Best fit
ChatGPT account (Plus/Pro/Business/Edu/Enterprise)	All entry points (CLI/IDE/App/Cloud)	Includes GitHub code review, Slack, and other cloud-based features	Individual subscribers and teams
API key	CLI, SDK, IDE Extension	Does not include GitHub code review, Slack, and other cloud-based features	CI, automation, and API-billed workflows

Pricing, usage limits, and exact feature access should be checked on the official pricing page and in your account dashboard. If you sign in with an API key and Cloud features are unavailable, that is a surface difference, not a broken setup.

CLI Entry Point

The CLI is a coding agent that runs in your local terminal. It can read code from the selected directory, edit files, run commands, and inspect results, so it works well when you already have a local repository.

CLI Definition and Use Cases

The CLI’s core job is to work inside a local repository: read code, edit files, run tests, run lint, inspect errors, and produce a diff. You do not need to have the file open in an editor. You only need to describe the task in the terminal.

Good fits for the CLI:

• You already have a local Git repository.
• The task touches multiple files or needs command-line verification.
• You want file changes to be visible locally for git diff and commits.
• You are using CI or script-based automation.

Poor fits for the CLI:

• You do not have a local repository yet, so you need to clone one first.
• You only want to edit the currently open file, where the IDE extension is smoother.
• You need a remote PR workflow, where Cloud is a better fit.

CLI Installation and Sign-In

Installation and sign-in can change over time, so treat this as the high-level flow and check the official CLI page for exact commands:

1. Choose the installation method from the official CLI page: the current official page provides a standalone installer. Older posts may mention npm installation, but the current official page should win.
2. Run it for the first time: after installation, run codex and follow the sign-in flow.
3. Choose the sign-in method: use either a ChatGPT account or an API key. A ChatGPT account covers all surfaces; an API key is limited to CLI, SDK, and IDE extension use, without Cloud features.

The CLI supports macOS, Windows, and Linux. On Windows, use the PowerShell native sandbox or WSL2 depending on the current official guidance.

Common CLI Commands

The CLI has interactive and non-interactive modes. These are the six commands or command groups a beginner should recognize first; names may change, so check the CLI reference when you need exact syntax.

Command	Purpose	Example
codex	Interactive mode for conversational work in the terminal	codex
codex exec	Non-interactive mode for CI or scripts	codex exec "fix the CI failure"
codex login	Sign in or switch accounts	codex login
codex update	Update the CLI	codex update
codex doctor	Check environment configuration and common issues	codex doctor
Common flags	Tune permissions, model, sandbox, and approval behavior	--sandbox read-only, --model, --ask-for-approval

The CLI reference includes more commands and flags, including codex apply, codex cloud, and codex app. Some commands may have different maturity levels. As a beginner, learn interactive mode first, then move to codex exec when you need automation.

Your First CLI Task

The first-task rule is simple: choose an existing repository and give Codex a task you can verify in about 20 minutes.

OpenAI’s best practices recommend a high-quality prompt with four parts:

Prompt part	Meaning	Example
Goal	The outcome you want	”Fix the outdated install command in the README”
Context	The relevant background	”This is a Node.js project. The README mentions npm install, but the project now uses yarn.”
Constraints	Boundaries for the change	”Only edit the README. Do not change other files. After editing, run node README-example.js to confirm the command works.”
Done when	The verification condition	”The README command is updated and node README-example.js prints the expected output.”

Good first tasks:

• Fix an outdated README command or link.
• Add a missing test or fix a failing test.
• Fix a small bug with a clear error message.
• Clean up a TODO comment.
• Add a simple type annotation to one module.

Avoid first tasks that:

• Touch secrets or production data.
• Require a large refactor or a full new feature.
• Have no clear acceptance condition, such as “optimize performance.”

CLI Review Checklist

After the CLI finishes, verify the result in this order:

1. Read the diff: run git diff in the terminal and confirm the change matches the request. Do not rely only on the final “done” message.
2. Run tests: if the project has tests, run npm test or the relevant command.
3. Run lint or typecheck: if the project has these checks, make sure no new errors were introduced.
4. Check command output: if the task required a command to run, confirm the output matches the expected result.
5. Keep secrets away from the first task: if a task touches sensitive configuration, review whether the change is necessary before letting an agent edit it.

Commit or push only after the checks pass. If the change is wrong, restore it with Git, tighten the prompt, and try again.

IDE Extension Entry Point

The IDE extension lets Codex work in your editor sidebar. It is a good fit when you are already working in the editor. Its advantage is shorter, sharper context: open files, selected code, and explicit @file references, without having to describe the whole project in a terminal prompt.

IDE Definition and Use Cases

The IDE extension does not replace the editor. It embeds Codex as a coding agent inside your editor workflow. The context comes from open files, selected snippets, or files you explicitly reference with @file, so it can be more precise for local edits.

Good fits for the IDE extension:

• You are working in VS Code, Cursor, Windsurf, or JetBrains.
• The task is about the current file or a small set of related files.
• You want to watch changes in the editor as they happen.
• You need to reference a specific file as context.

Poor fits for the IDE extension:

• You are not using an editor environment, where the CLI is simpler.
• The task needs long background execution, where Cloud can take over.
• The task touches many files or complex command flows, where the CLI or Cloud may be better.

Supported IDEs

The IDE extension supports these editors; check the official IDE page for current availability:

Editor	Notes
VS Code	Officially supported
Cursor	A VS Code fork compatible with the VS Code extension
Windsurf	A VS Code fork compatible with the VS Code extension
JetBrains	Supports Rider, IntelliJ, PyCharm, WebStorm, and related IDEs, subject to official availability

If you work in Cursor or Windsurf, the Codex extension and the editor’s built-in AI features can sit side by side. Codex is another coding agent you can switch to when it fits the task.

IDE Installation and Sign-In

Use the official IDE page for current installation steps:

1. Install from the extension marketplace: search for the Codex extension in VS Code, Cursor, Windsurf, or JetBrains.
2. Sign in: use a ChatGPT account or an API key. A ChatGPT account covers all surfaces; an API key does not include Cloud features.

IDE Context

The IDE extension’s main value is editor context:

Context type	What it means	Example
Open files	Currently open files are available as context	Open example.tsx, and Codex can inspect it directly
Selected code	The selected snippet becomes context	Select a function and ask Codex to explain or refactor it
@file reference	Explicitly reference another file by name	@example.tsx please check the component's type definitions
Reasoning effort	Adjust how much reasoning the agent uses	low/medium/high; use higher effort for harder tasks

The IDE extension also supports Chat, Agent, and Agent Full Access modes. The difference is permission and automation level. Start with the default Agent mode, then adjust once you understand the trade-offs.

Delegating from IDE to Cloud

The IDE extension can delegate work to Codex Cloud. Use that when:

• The task may run for a long time.
• The task involves a remote repository.
• You need to leave the machine while work continues.
• You want a complex task to run in the background and review the result later.

Common slash commands may include the following; command names can change, so check the IDE features page:

Command	Purpose
/cloud	Delegate the current task to Cloud
/local	Run the task locally
/review	Review the base branch, uncommitted changes, or a commit
/status	Check Cloud task status

After you use /cloud, the IDE shows task status. When the Cloud task finishes, return to review the diff and result.

Codex App Entry Point

Codex app is a desktop command center for multi-threaded work and Git management. It is not another chat window. It can pick up history and configuration from the CLI and IDE extension, which makes it useful for continuing work on an existing project.

App Definition and Use Cases

The app focuses on multiple threads, worktrees, automations, and Git operations. It is useful when you need parallel tasks, a diff pane, and Git integration in one local workspace.

Good fits for the app:

• You need several task threads at the same time.
• You need isolated parallel work through worktrees.
• You want a visual diff pane and Git operations.
• You want a desktop workflow with an integrated terminal.

Poor fits for the app:

• You only want to edit the current file, where the IDE extension is smoother.
• You do not have a local repository, in which case use Cloud or clone the repo first.
• You only need one quick task, where the CLI is faster.

App Platform Support

Codex app supports macOS and Windows. Check the official app page for Linux availability.

App Installation and Sign-In

Use the official app page for current steps:

1. Download and install: get the macOS or Windows installer from the official app page.
2. Sign in: use a ChatGPT account or an API key. Some features may be unavailable with an API key, depending on the official guidance.
3. Choose a project: the first launch asks you to select a local project directory.

App Thread Modes

The app provides three thread modes: Local, Worktree, and Cloud.

Thread mode	What it does	Best for
Local	Works directly in the current project directory	Small changes, single-threaded work, the default first message
Worktree	Creates an isolated worktree for the thread	Parallel tasks, isolated changes, avoiding conflicts
Cloud	Delegates the task to Codex Cloud	Remote repositories, PRs, long-running tasks

Save the detailed worktree workflow for a later guide. As a beginner, start with Local mode.

App Core Features

The app’s core features include:

Feature	What it does
Diff pane	Lets you visually inspect file changes and stage or revert chunks
Git operations	Supports commit, push, PR creation, and related Git flow actions
Integrated terminal	Cmd+J on macOS opens the terminal; check the official page for current shortcuts
IDE sync	IDE extension and app workflows can sync within the same project
Shared MCP settings	CLI, IDE, and app can share MCP settings

The app also includes an in-app browser, but it does not use pages that require your logged-in browser profile. Open login-gated pages in an external browser when needed.

Codex Cloud/Web Entry Point

Codex web/cloud connects to a GitHub account and lets Codex work in a remote repository and create PRs. It fits team workflows, remote repositories, and tasks you want to keep running while you are away from your computer.

Cloud Definition and Use Cases

Cloud is about remote repositories, PRs, and asynchronous work. It creates a cloud container, checks out the repository, runs setup scripts, executes the task, and returns a diff and response.

Good fits for Cloud:

• Remote repositories that you do not want to modify locally.
• PR flows where Codex should create or review a PR.
• Work that should continue while you are away.
• Team workflows with review and collaboration.

Poor fits for Cloud:

• Small local changes, where the CLI or IDE extension is better.
• Your very first task, which should be verified locally first.
• Highly interactive tasks, because Cloud is asynchronous.

Good Cloud Tasks

Cloud works well for these task types:

Task type	Notes
PR review	Review a PR in a remote repository
Complex or long-running work	Run tasks that need more time
Parallel tasks	Delegate several tasks at the same time
Remote repository changes	Make changes without touching your local checkout

Do not send a large refactor or full feature to Cloud on day one. First use the CLI or IDE locally, learn how the result looks, then move suitable tasks to Cloud.

Enterprise workspaces may need admin setup. Check the official Cloud page and your workspace policy.

Cloud Flow

A Cloud task roughly follows five steps:

1. Create a container: Cloud creates the runtime environment.
2. Check out the repository: it checks out the GitHub repository.
3. Run the setup script: it runs the configured setup script, if one exists.
4. Execute the agent loop: the agent runs commands, checks results, and continues until the task is done.
5. Return the diff and answer: the finished task shows the diff and a response.

Container caching can last up to 12 hours. Check the official Cloud environments page for the current cache policy.

Cloud Security Notes

Cloud has a few important security boundaries:

Security item	What it means
Secrets are only available during setup	Secrets are available to setup scripts and removed before the agent phase. Do not make the agent phase depend on scripts that read secrets.
The agent phase has no internet by default	Internet access is off by default during the agent phase, though limited or unrestricted access can be configured. Do not assume the agent can reach external services.
Cache lasts up to 12 hours	Container cache is not long-term storage. Do not assume state will persist indefinitely.

For deeper security configuration, use the later guide on permissions, sandboxes, and secrets.

Next Steps

After the first task, if Codex keeps making the same mistake on the second or third run, write an AGENTS.md project guide. AGENTS.md gives coding agents project-specific instructions so you do not repeat the same context in every prompt.

Recommended follow-up topics:

• AGENTS.md project rules: preserve project guidance and reduce repeated context.
• Worktree isolation: run multiple tasks in parallel without mixing changes.
• Cloud workflow: remote repositories, PRs, and environment setup.
• Permissions, sandboxes, and secrets: security boundaries and configuration.
• Three-tool comparison: Codex vs Claude Code vs Cursor in real projects.
• codex exec automation: CI calls and script-based automation.

Related BetterLink articles:

• 2026 AI coding tools overview
• Claude Code CLI productivity guide
• Cursor workflow practice
• Codex gateway and harness