---
name: codex-gpt-image2
description: Use when the user wants to generate PNG images with OpenAI gpt-image-2 through their local Codex login, without Hermes, OpenClaw, OpenAI API keys, or the OpenAI Python SDK. Also use when another CLI/agent needs a shell command for image generation from a prompt via ~/.codex/auth.json.
---

# Codex GPT Image 2

Generate images through the standalone CLI in this repository. It uses local
Codex auth from `$CODEX_HOME/auth.json` or `~/.codex/auth.json`, calls the
Codex Responses endpoint, and writes a PNG file.

## Command

From this repository root:

```bash
./codex-gpt-image2 \
  --prompt "A minimal blue circle centered on a white background" \
  --aspect square \
  --quality medium \
  --output out.png
```

For scripts and other agents, prefer JSON output:

```bash
./codex-gpt-image2 \
  --prompt "A cinematic product hero image" \
  --aspect landscape \
  --quality high \
  --output hero.png \
  --json
```

If the wrapper is unavailable, call the Python file directly:

```bash
python3 codex_gpt_image2.py --prompt "simple icon" --aspect square --json
```

## Parameters

- `--prompt`, `-p`: required image prompt.
- `--aspect`, `-a`: `landscape`, `square`, or `portrait`.
- `--quality`, `-q`: `low`, `medium`, or `high`.
- `--output`, `-o`: output PNG path. If omitted, the tool writes a timestamped PNG in the current directory.
- `--codex-home`: custom Codex home directory.
- `--timeout`: request timeout in seconds.
- `--json`: machine-readable result.

## Error Handling

Do not inspect or print tokens. If the command reports missing or expired Codex
auth, tell the user to run `codex` locally and sign in or refresh the session,
then retry. HTTP 401/403 usually means the local Codex login is invalid or the
account cannot access the image generation tool.

The tool intentionally has no dependency on Hermes, OpenClaw, or the OpenAI
Python SDK.