> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/openai/codex/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get up and running with Codex CLI in minutes

# Quickstart

This guide will help you get Codex CLI running and execute your first commands. You'll go from installation to your first AI-powered task in just a few minutes.

## Before you begin

Make sure you have:

* Codex CLI installed (see [Installation](/installation))
* A ChatGPT account (Plus, Pro, Team, Edu, or Enterprise) or an OpenAI API key
* A terminal running macOS 12+, Linux (Ubuntu/Debian), or Windows 11 with WSL2

## Get started with Codex

<Steps>
  <Step title="Install Codex CLI">
    Install Codex globally using npm or Homebrew:

    <CodeGroup>
      ```bash npm theme={null}
      npm install -g @openai/codex
      ```

      ```bash Homebrew theme={null}
      brew install --cask codex
      ```
    </CodeGroup>

    Verify the installation:

    ```bash theme={null}
    codex --version
    ```
  </Step>

  <Step title="Sign in with ChatGPT">
    Run `codex` and select **Sign in with ChatGPT**. This is the recommended method for using Codex with your ChatGPT plan.

    ```bash theme={null}
    codex
    ```

    When you run this command, Codex will:

    1. Start a local login server on `http://localhost` (random port)
    2. Open your browser to authenticate
    3. Complete authentication and return to the terminal

    <Note>
      We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. [Learn more about what's included in your ChatGPT plan](https://help.openai.com/en/articles/11369540-codex-in-chatgpt).
    </Note>

    **On a remote or headless machine?** Use device code authentication instead:

    ```bash theme={null}
    codex login --device-auth
    ```

    Alternatively, you can use an API key (see [Authentication](/authentication) for details).
  </Step>

  <Step title="Run your first command">
    Once authenticated, run Codex interactively:

    ```bash theme={null}
    codex
    ```

    Or provide a prompt directly:

    ```bash theme={null}
    codex "explain this codebase to me"
    ```

    Codex will analyze your project and provide an explanation.
  </Step>

  <Step title="Try an example task">
    Let's have Codex write a simple script. Try this command:

    ```bash theme={null}
    codex "create a simple Python script that prints Hello World"
    ```

    Codex will:

    1. Create a Python file
    2. Write the code
    3. Ask for your approval before saving (in default "suggest" mode)
    4. Show you the result

    You'll see output similar to:

    ```
    I'll create a simple Python script for you.

    [Codex proposes changes]

    Approve? [Y/n]:
    ```

    Type `y` to approve and apply the changes.
  </Step>
</Steps>

## Understanding approval modes

Codex operates in three approval modes that control how much autonomy the agent has:

<CardGroup cols={3}>
  <Card title="Suggest" icon="hand">
    **Default mode**

    Codex reads files and suggests changes. You approve all file writes and shell commands.
  </Card>

  <Card title="Auto Edit" icon="pen-to-square">
    Codex reads and writes files automatically. You approve shell commands.

    Use: `codex --approval-mode auto-edit`
  </Card>

  <Card title="Full Auto" icon="robot">
    Codex reads, writes files, and executes commands autonomously. Everything runs in a sandbox.

    Use: `codex --approval-mode full-auto`
  </Card>
</CardGroup>

<Warning>
  In full auto mode, commands run network-disabled and confined to your working directory. Codex will warn you if your directory is not tracked by Git.
</Warning>

## Example workflows

Here are some common tasks you can ask Codex to perform:

<Accordion title="Refactor code">
  ```bash theme={null}
  codex "Refactor the Dashboard component to React Hooks"
  ```

  Codex will:

  * Read the component file
  * Rewrite it using React Hooks
  * Run tests to verify the changes
  * Show you a diff of the changes
</Accordion>

<Accordion title="Generate tests">
  ```bash theme={null}
  codex "Write unit tests for utils/date.ts"
  ```

  Codex will:

  * Analyze the `date.ts` file
  * Generate comprehensive unit tests
  * Execute the tests
  * Iterate until they pass
</Accordion>

<Accordion title="Create a full application">
  ```bash theme={null}
  codex --approval-mode full-auto "create a todo-list app with React and TypeScript"
  ```

  Codex will:

  * Scaffold the project structure
  * Install dependencies
  * Write the application code
  * Run it in the sandbox
  * Show you the live result
</Accordion>

<Accordion title="Fix errors">
  ```bash theme={null}
  codex "fix all TypeScript errors in this project"
  ```

  Codex will:

  * Run the TypeScript compiler
  * Identify all type errors
  * Fix them one by one
  * Verify the fixes compile
</Accordion>

## Interactive vs non-interactive mode

**Interactive mode** (default)

Run `codex` to start an interactive REPL session:

```bash theme={null}
codex
```

You can have a back-and-forth conversation with Codex, approve changes, and iterate on tasks.

**Non-interactive mode**

Provide a prompt as a command-line argument:

```bash theme={null}
codex "create a README for this project"
```

Codex will execute the task and exit when complete.

**Quiet mode** (for CI/CD)

Run Codex headless in pipelines:

```bash theme={null}
codex -q "update CHANGELOG for next release"
```

Or set the environment variable:

```bash theme={null}
export CODEX_QUIET_MODE=1
```

## Passing images

Codex is multimodal and can understand images. Pass screenshots or diagrams:

```bash theme={null}
codex -i screenshot.png "implement this design"
```

Codex will analyze the image and implement the visual design.

## Next steps

<CardGroup cols={2}>
  <Card title="Learn about authentication" icon="key" href="/authentication">
    Explore all authentication methods and configuration options
  </Card>

  <Card title="Core concepts" icon="book" href="/core-concepts">
    Understand approval modes, sandboxing, and security model
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Customize Codex with config files and environment variables
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli-reference">
    Explore all available commands and options
  </Card>
</CardGroup>