# How to Use Slash Commands Within Codex CLI: A Developer Guide

> Learn how developers use slash commands in Codex CLI. Trigger handler functions via the TypeScript SDK with simple forward-slash inputs. This guide details the five-stage detection pipeline.

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

---

**Developers can use slash commands within Codex CLI by typing any input that begins with a forward-slash (`/`), which triggers a five-stage detection and execution pipeline that delegates to handler functions in the TypeScript SDK.**

The OpenAI Codex CLI provides a powerful terminal interface for AI-assisted coding workflows through simple text commands. By leveraging slash commands within Codex CLI, developers can trigger complex operations—from generating implementation plans to executing sandboxed scripts—without leaving their terminal. This architecture separates lightweight parsing logic in the CLI entry point from heavy-duty execution handlers in the SDK, making it straightforward to extend functionality.

## How Slash Commands Work in the Codex CLI

The Codex CLI processes slash commands through a streamlined pipeline that keeps the parser minimal while delegating actual work to the SDK.

### Command Detection and Parsing

When you type a line starting with `/`, the CLI entry point at [`codex-cli/bin/codex.js`](https://github.com/openai/codex/blob/main/codex-cli/bin/codex.js) detects the leading character and splits the input into a command name and an optional argument string. For example, input `/plan my-task` is separated into the command `plan` and the argument string `my-task`.

### Command Lookup and Execution

The command name is matched against the built-in table defined in [`docs/slash_commands.md`](https://github.com/openai/codex/blob/main/docs/slash_commands.md). Each entry maps to a specific handler function in the TypeScript SDK, such as `CodexOptions.handlePlan` located in [`sdk/typescript/src/codexOptions.ts`](https://github.com/openai/codex/blob/main/sdk/typescript/src/codexOptions.ts). The handler constructs the appropriate request payload—for example, a `PlanRequest` or `ListPlansRequest`—and transmits it to the Codex back-end via the high-level client in [`sdk/typescript/src/codex.ts`](https://github.com/openai/codex/blob/main/sdk/typescript/src/codex.ts).

### Result Handling

After execution, the CLI prints the response to the terminal, updates the TUI interface if running in interactive mode, and persists any side effects such as newly generated plan files.

## Built-in Slash Command Examples

Here are practical examples of how to use slash commands within Codex CLI for common development tasks:

### Creating Implementation Plans with /plan

Use the `/plan` command to generate structured implementation plans for new features:

```bash
$ codex /plan "Add a new feature to the API"

```

The CLI parses `plan` as the command and the quoted string as the argument. Internally, this invokes the `handlePlan` method in [`sdk/typescript/src/codexOptions.ts`](https://github.com/openai/codex/blob/main/sdk/typescript/src/codexOptions.ts), which builds a `PlanRequest` and posts it to the server.

### Executing Scripts with /run

The `/run` command executes generated scripts in a sandboxed environment:

```bash
$ codex /run my_script.sh

```

According to the command table in [`docs/slash_commands.md`](https://github.com/openai/codex/blob/main/docs/slash_commands.md), the `run` handler executes the script and streams the output back to your terminal in real time.

### Listing Resources with /list-plans

To view recent plans without providing arguments:

```bash
$ codex /list-plans

```

This sends a `ListPlansRequest` through the SDK, and the CLI formats the returned JSON into a readable table for quick review.

## Key Implementation Files

The following files define the slash command architecture according to the OpenAI Codex source code:

- **[`codex-cli/bin/codex.js`](https://github.com/openai/codex/blob/main/codex-cli/bin/codex.js)** – Entry point that scans for leading `/` characters and initiates command dispatch.
- **[`docs/slash_commands.md`](https://github.com/openai/codex/blob/main/docs/slash_commands.md)** – Authoritative registry of all built-in slash commands and their semantics.
- **[`docs/tui-chat-composer.md`](https://github.com/openai/codex/blob/main/docs/tui-chat-composer.md)** – Documents auto-completion and display behavior for slash commands in the interactive TUI.
- **[`sdk/typescript/src/codexOptions.ts`](https://github.com/openai/codex/blob/main/sdk/typescript/src/codexOptions.ts)** – Implements concrete handlers like `handlePlan` and `handleRun` that build request payloads.
- **[`sdk/typescript/src/codex.ts`](https://github.com/openai/codex/blob/main/sdk/typescript/src/codex.ts)** – High-level client used by the CLI to send requests and process responses from the back-end.

## Summary

- Slash commands within Codex CLI begin with a forward-slash (`/`) and are detected in [`codex-cli/bin/codex.js`](https://github.com/openai/codex/blob/main/codex-cli/bin/codex.js).
- The parser splits commands into names and arguments, then looks up handlers in the table defined in [`docs/slash_commands.md`](https://github.com/openai/codex/blob/main/docs/slash_commands.md).
- Handlers such as `CodexOptions.handlePlan` in [`sdk/typescript/src/codexOptions.ts`](https://github.com/openai/codex/blob/main/sdk/typescript/src/codexOptions.ts) construct requests like `PlanRequest` and delegate to the back-end.
- Results are displayed in the terminal, with TUI updates and side-effect persistence handled automatically.
- The modular architecture allows extending functionality by adding entries to the command table and implementing new SDK handlers.

## Frequently Asked Questions

### How does the Codex CLI detect slash commands?

The CLI scans input lines for a leading forward-slash (`/`) at the entry point in [`codex-cli/bin/codex.js`](https://github.com/openai/codex/blob/main/codex-cli/bin/codex.js). When detected, the line is treated as a command rather than natural language input, triggering the parsing and execution pipeline immediately.

### Where are slash command handlers implemented?

Concrete handlers are implemented in the TypeScript SDK at [`sdk/typescript/src/codexOptions.ts`](https://github.com/openai/codex/blob/main/sdk/typescript/src/codexOptions.ts). For example, the `handlePlan` method constructs a `PlanRequest` payload, while `handleRun` manages script execution in sandboxed environments.

### Can I add custom slash commands to the Codex CLI?

Yes. The architecture separates the lightweight CLI parser from the SDK logic. To add a command, you register it in [`docs/slash_commands.md`](https://github.com/openai/codex/blob/main/docs/slash_commands.md) and implement the corresponding handler function in [`sdk/typescript/src/codexOptions.ts`](https://github.com/openai/codex/blob/main/sdk/typescript/src/codexOptions.ts), following the pattern used by existing commands like `handlePlan`.

### What is the difference between /plan and /run commands?

The `/plan` command generates implementation plans by sending a `PlanRequest` to the back-end and creating plan files, while `/run` executes existing scripts in a sandboxed environment and streams real-time output back to the terminal, as defined in the command table at [`docs/slash_commands.md`](https://github.com/openai/codex/blob/main/docs/slash_commands.md).