# What Is the CLI Directory in the OpenAI Codex Project?

> Explore the CLI directory in the OpenAI Codex project. Discover how it implements the command-line interface for legacy TypeScript and modern Rust binaries, handling parsing, loading, and sandboxed execution.

- Repository: [OpenAI/codex](https://github.com/openai/codex)
- Tags: internals
- Published: 2026-03-06

---

**The `cli/` (formally `codex-cli/`) directory contains the Command-Line Interface implementation that exposes Codex as both a legacy TypeScript npm package and a modern Rust binary, handling argument parsing, configuration loading, and secure sandboxed execution.**

The OpenAI Codex repository provides a powerful AI coding agent that can be invoked programmatically or via terminal. The **CLI directory** serves as the primary frontend, translating user commands into structured instructions for the underlying engine. Whether installed via `npm install -g @openai/codex` or compiled from Rust source, this directory contains the entry points and logic required to run Codex interactively or in automated CI pipelines.

## Core Responsibilities of the CLI Directory

The CLI implementation spans two distinct architectures—TypeScript for legacy support and Rust for current development—unified under the `codex-cli/` path.

### Executable Distribution and Package Management

The directory exposes the `codex` command through dual distribution channels. In [`codex-cli/package.json`](https://github.com/openai/codex/blob/main/codex-cli/package.json), the `bin` field maps the command to [`dist/index.js`](https://github.com/openai/codex/blob/main/dist/index.js), enabling global installation via npm as `@openai/codex`. Concurrently, the Rust implementation builds a native binary through `cargo build -p codex-cli --bin codex`, providing a performance-optimized alternative located within the broader `codex-rs/` workspace.

### Argument Parsing and Configuration Loading

Command-line flags such as `--provider`, `--approval-mode`, and `--config` are parsed in Rust source files including [`codex-rs/exec/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/exec/src/cli.rs) and [`codex-rs/tui/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/tui/src/cli.rs). The CLI automatically detects and loads environment variables from `.env` files, merging these with explicit configuration files to establish runtime parameters including API keys and model selection.

### Execution Modes and Security Sandboxing

The directory supports multiple invocation patterns: interactive REPL sessions, one-shot prompt execution, and CI-friendly full-auto mode. Security is enforced through platform-specific sandboxing—macOS utilizes Apple Seatbelt profiles while Linux deployments leverage Docker containers via [`codex-cli/scripts/run_in_container.sh`](https://github.com/openai/codex/blob/main/codex-cli/scripts/run_in_container.sh) to ensure network-disabled, restricted execution environments.

## Key Files and Architecture

Understanding the file structure within `codex-cli/` reveals how the interface layers communicate with core libraries:

- **[`codex-cli/package.json`](https://github.com/openai/codex/blob/main/codex-cli/package.json)** – Defines npm metadata, dependencies, and the binary entry point for the TypeScript distribution.
- **[`codex-cli/README.md`](https://github.com/openai/codex/blob/main/codex-cli/README.md)** – Documents CLI flags, approval modes, and platform-specific sandboxing requirements.
- **`codex-cli/scripts/`** – Contains helper utilities including [`run_in_container.sh`](https://github.com/openai/codex/blob/main/run_in_container.sh) for Docker sandboxing and [`install_native_deps.py`](https://github.com/openai/codex/blob/main/install_native_deps.py) for dependency management.
- **[`codex-rs/exec/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/exec/src/cli.rs)** – Implements the primary Rust-based argument parser and execution orchestrator.
- **[`codex-rs/file-search/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/file-search/src/cli.rs)** – Handles CLI interactions for the file-search utility integrated into Codex.
- **[`codex-rs/tui/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/tui/src/cli.rs)** – Manages terminal UI-specific command handling, including clipboard integration features.
- **`codex-rs/exec/tests/suite/cli_responses_fixture.sse`** – Test fixture used by the CLI test suite to validate server-sent event handling.

## Practical Usage Examples

### Install the Legacy TypeScript CLI

For users requiring the Node.js-based implementation:

```bash
npm install -g @openai/codex

```

### Launch Interactive Mode

Start the REPL for conversational coding assistance:

```bash
codex

```

### Execute One-Shot Prompts

Run a single command without entering interactive mode:

```bash
codex "explain this codebase to me"

```

### Specify Alternative Providers

Route requests to local models such as Ollama using the provider flag defined in [`codex-rs/exec/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/exec/src/cli.rs):

```bash
codex --provider ollama "write a Python script that fetches the weather"

```

### Enable Full-Auto Approval for CI

Permit automated file modifications and sandboxed command execution without human intervention:

```bash
codex --approval-mode full-auto "generate a README for this repository"

```

### Run Within Container Sandbox

Execute Codex in an isolated environment using the provided container script:

```bash
cd codex-cli
./scripts/run_in_container.sh codex "list all TODOs in the repo"

```

This script mounts the current repository and enforces network isolation as detailed in the **Security model & permissions** documentation.

## Summary

- The **CLI directory** (`codex-cli/`) functions as the frontend gateway for the OpenAI Codex project, exposing functionality through both npm and Rust binary distributions.
- **Argument parsing** occurs in Rust source files including [`codex-rs/exec/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/exec/src/cli.rs), handling flags for providers, approval modes, and configuration paths.
- **Security sandboxing** is implemented via platform-specific mechanisms—Apple Seatbelt on macOS and Docker containers on Linux—managed through scripts in `codex-cli/scripts/`.
- The directory supports **multiple execution modes** ranging from interactive REPLs to automated CI pipelines with full-auto approval.

## Frequently Asked Questions

### What is the relationship between the TypeScript and Rust implementations in the CLI directory?

The TypeScript implementation in [`codex-cli/package.json`](https://github.com/openai/codex/blob/main/codex-cli/package.json) provides legacy npm distribution as `@openai/codex`, while the Rust code in `codex-rs/*/src/cli.rs` files represents the current high-performance binary. Both share the same command interface but the Rust version is actively developed for production use and can be built using `cargo build -p codex-cli --bin codex`.

### How does the Codex CLI handle security and sandboxing?

According to the source code in [`codex-cli/scripts/run_in_container.sh`](https://github.com/openai/codex/blob/main/codex-cli/scripts/run_in_container.sh) and the documented security model, the CLI implements platform-specific sandboxing using Apple Seatbelt profiles on macOS and Docker containers with network disabled on Linux. The `--approval-mode` flag controls permission levels, with `full-auto` allowing sandboxed command execution without interactive prompts.

### Where are command-line arguments parsed in the Codex source code?

CLI arguments are parsed in several Rust files within the `codex-rs/` workspace, specifically [`codex-rs/exec/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/exec/src/cli.rs) for the main execution flow, [`codex-rs/tui/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/tui/src/cli.rs) for terminal UI features, and [`codex-rs/file-search/src/cli.rs`](https://github.com/openai/codex/blob/main/codex-rs/file-search/src/cli.rs) for search utilities. These parsers handle flags like `--provider`, `--config`, and `--approval-mode`.

### Can the Codex CLI be used without Node.js installed?

Yes. While the legacy TypeScript version requires Node.js, the Rust binary can be compiled and executed natively using `cargo build -p codex-cli --bin codex`. This produces a standalone executable that does not depend on the Node.js runtime, though Docker may be required for full sandboxing functionality on Linux systems.