Skip to content

Getting Started with Codex CLI

Start using Codex CLI in a project and manage common workflows.

Get started with Codex CLI

Launch Codex from a project directory, then give it a clear task.

Create a project directory

Codex should normally be launched from inside the project directory you want it to work with.

Create a test project:

mkdir -p ~/codex-project

Enter the directory:

cd ~/codex-project

Start Codex

Start Codex from inside the project directory:

codex

The Codex terminal interface will open.

You can now describe the task you want Codex to perform.

For example:

Explain what files are currently in this project.

For an empty test project, you could ask:

Create a simple Python web server that displays a welcome page.

Codex may then:

  1. Inspect the current directory
  2. Propose a plan
  3. Create or edit files
  4. Ask for permission before running certain commands
  5. Display the changes it has made

Create project instructions

Inside the Codex interface, run:

/init

This creates an AGENTS.md file for the project.

The file can contain instructions that Codex should follow while working in that directory, such as:

# Project Instructions

- Use Python 3.
- Add comments to important functions.
- Do not delete existing files without asking.
- Run tests after modifying the application.
- Keep documentation up to date.

Codex reads these instructions when working with the project.

Useful Codex commands

The following commands can be entered inside the interactive Codex interface.

Display the current session status

/status

This displays information about the current session, model, directory, and configuration.

Change the model

/model

This allows you to select an available model and reasoning level.

Configure permissions

/permissions

This allows you to control what Codex is permitted to do in the current environment.

Review changes

/review

This asks Codex to review code changes and identify possible problems.

Display available commands

/help

You can also press:

?

to display keyboard shortcuts.

Exit Codex

Use:

/exit

You can also press Ctrl+C when appropriate.

Start with an initial task

You can provide the first task when launching Codex:

codex "Explain the structure of this project"

Another example:

codex "Review this project and identify possible configuration problems"

Codex will start inside the current directory and immediately process the supplied request.

Run a non-interactive task

Codex also supports non-interactive execution with codex exec.

For example:

codex exec "Explain the purpose of this project"

This is useful for:

  • Shell scripts.
  • Automated checks.
  • CI/CD pipelines.
  • Repeatable development workflows.

Use automated commands carefully

Carefully test automated Codex commands before using them in production environments.

Resume a previous session

To reopen a previous Codex session, run:

codex resume

Codex will allow you to select a previous session.

This is helpful when returning to an unfinished task without starting the conversation again.

Update Codex

The official standalone installation command can also install the latest available version:

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

After updating, confirm the installed version:

codex --version

Some Codex releases may also support:

codex update

Sign out

To remove the current Codex authentication credentials, run:

codex logout

Verify that you have been signed out:

codex login status

Codex configuration directory

Codex normally stores its local configuration and session information inside:

~/.codex

You can view the directory with:

ls -la ~/.codex

The main configuration file is normally:

~/.codex/config.toml

Authentication information may be stored in:

~/.codex/auth.json

Protect your authentication file

Treat ~/.codex/auth.json like a password. It may contain authentication tokens. Never publish it, send it to another person, or commit it to Git.

Installation command summary

The following commands cover the basic installation process on Ubuntu:

sudo apt update
sudo apt install curl git ca-certificates -y
curl -fsSL https://chatgpt.com/codex/install.sh | sh
exec "$SHELL" -l
codex --version
codex login --device-auth

After signing in, open your project directory and start Codex:

cd /path/to/project
codex

Next steps

OpenAI Codex brings AI-assisted software development directly into the Linux terminal. Once installed and authenticated, it can inspect projects, explain code, modify files, execute development tools, review changes, and help troubleshoot technical problems.

For the safest workflow, launch Codex as a normal Linux user, work inside a Git repository, create checkpoints before major tasks, and review every command or file change before applying it to a production system.

Return to Set up OpenAI Codex on Linux for installation and sign-in steps.