# How to Configure Custom Prompts in the Codex CLI: A Complete Guide

> Master the Codex CLI: Learn to configure custom prompts using YAML or JSON files for efficient command-line interactions. Boost your productivity today.

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

---

**You configure custom prompts in the Codex CLI by creating a YAML (or JSON) file that maps short names to full prompt texts, then pointing the CLI to that file via the `--prompt-file` flag or the `CODEX_PROMPT_FILE` environment variable.**

The openai/codex repository provides a flexible system for managing reusable system prompts. By configuring custom prompts, you can standardize repetitive tasks—such as lint fixing or code review—across both interactive and automated workflows without retyping lengthy instructions.

## Creating a Custom Prompt Definition File

Custom prompts are stored in a definition file that maps identifiers to prompt content. According to the documentation in [`docs/prompts.md`](https://github.com/openai/codex/blob/main/docs/prompts.md), the file supports YAML or JSON format and requires two fields per entry: `description` (a human-readable summary) and `prompt` (the full instruction text).

Create a file at `~/.config/codex/prompts.yaml` with the following structure:

```yaml

# ~/.config/codex/prompts.yaml

fix_lint:
  description: "Fix lint errors in the current project"
  prompt: |
    You are a lint-fixing assistant.
    • Analyze the current repository.
    • Identify all lint violations.
    • Generate the minimal set of changes to make the code pass `cargo fmt` and `cargo clippy`.

review_pr:
  description: "Review a pull-request"
  prompt: |
    Act as a senior engineer reviewing a PR.
    • Summarize the change.
    • Point out potential bugs, style issues, or missing tests.
    • Suggest improvements.

```

Each top-level key (`fix_lint`, `review_pr`) becomes the command name you invoke later.

## Configuring the CLI to Locate Your Prompts

The Codex CLI must know where to find your definition file. As implemented in the `codex-cli` source, you have two configuration options:

**Environment Variable (Persistent)**
Set `CODEX_PROMPT_FILE` to the absolute path in your shell configuration:

```bash
export CODEX_PROMPT_FILE=$HOME/.config/codex/prompts.yaml

```

**Command-Line Flag (Per-Invocation)**
Pass the path explicitly using `--prompt-file`:

```bash
codex exec --prompt-file $HOME/.config/codex/prompts.yaml "fix_lint"

```

If both are provided, the command-line flag typically takes precedence, though you should verify behavior in [`codex-cli/README.md`](https://github.com/openai/codex/blob/main/codex-cli/README.md) for your specific version.

## Using Custom Prompts in Interactive and Batch Mode

Once configured, you invoke prompts by name. The CLI expands the short name into the full prompt text before sending it to the model.

### Interactive REPL Usage

In the TUI chat composer (documented in [`docs/tui-chat-composer.md`](https://github.com/openai/codex/blob/main/docs/tui-chat-composer.md)), type the slash command `/prompts:` followed by the prompt name:

```bash
codex
> /prompts: fix_lint

```

The composer automatically expands this into the full prompt text defined in your YAML file.

### Batch Execution (Full-Auto Mode)

For non-interactive automation with `codex exec`, reference the prompt name as the argument:

```bash
codex exec --prompt-file $HOME/.config/codex/prompts.yaml "review_pr"

```

This allows unattended workflows where the CLI runs entirely without user interaction.

### Inline One-Off Prompts

For ad-hoc tasks that do not warrant a permanent definition file, use the `--prompt` flag to embed the instruction directly:

```bash
codex exec --prompt "You are a helpful assistant that writes unit tests for the given Rust function." "$(cat src/lib.rs)"

```

## Managing and Discovering Available Prompts

To view all prompts defined in the currently loaded prompt file, use the `codex prompts` sub-command as described in [`codex-cli/README.md`](https://github.com/openai/codex/blob/main/codex-cli/README.md):

```bash
codex prompts list

# or

codex prompts ls

```

This outputs the names and descriptions of every entry in your [`prompts.yaml`](https://github.com/openai/codex/blob/main/prompts.yaml), helping you verify which shortcuts are available before invoking them.

## Summary

- **Create** a YAML file with named entries containing `description` and `prompt` fields.
- **Configure** the path via `CODEX_PROMPT_FILE` environment variable or `--prompt-file` flag.
- **Invoke** prompts by name using `/prompts: name` in the REPL or `codex exec "name"` in scripts.
- **List** available prompts anytime with `codex prompts list` to verify your configuration.
- **Use** `--prompt` for single-use instructions without creating a definition file.

## Frequently Asked Questions

### What file format does Codex CLI use for custom prompts?

The Codex CLI accepts both YAML and JSON formats for prompt definition files. The file must contain top-level keys that map to objects with `description` and `prompt` fields, as documented in [`docs/prompts.md`](https://github.com/openai/codex/blob/main/docs/prompts.md).

### Can I store my prompt file in a different directory than `~/.config/codex`?

Yes. You can place the file anywhere on your filesystem. You must tell the CLI where to find it by either setting the `CODEX_PROMPT_FILE` environment variable to the absolute path or passing the `--prompt-file` flag with every invocation.

### How do I use a custom prompt without creating a definition file?

For one-off tasks, use the `--prompt` flag with `codex exec` followed by the literal prompt text in quotes. This bypasses the need for a YAML file entirely, though the prompt will not be reusable across sessions without retyping it.

### Why does my prompt name not expand in the TUI composer?

Ensure you are using the exact syntax `/prompts: name` (with the colon and space) as specified in [`docs/tui-chat-composer.md`](https://github.com/openai/codex/blob/main/docs/tui-chat-composer.md). Also verify that your `CODEX_PROMPT_FILE` environment variable is set in the same shell session where you launched `codex`, or that you launched the CLI with the `--prompt-file` flag.