codex-img-cli

Give any agent GPT-Image generation, by reusing the Codex / ChatGPT subscription you already pay for.

Codex CLI ships an imagegen skill — but it lives inside the agent, so nothing else can reach it. Claude Code, MiniMax Code, OpenCode, Cursor, your own scripts… none of them can turn your ChatGPT plan into an image.

codex-img-cli extracts the exact same endpoint into a standalone CLI and an MCP stdio server. Point any MCP client at it and "draw me a picture" becomes a tool call.

Zero runtime dependencies · Node.js ≥ 20 · credentials never leave your machine

English | 简体中文

Why

Related MCP server: image-generation-mcp

How it works

The request shape is taken from the openai/codex source (codex-rs/ext/image-generation/src/):

POST https://chatgpt.com/backend-api/codex/images/generations
POST https://chatgpt.com/backend-api/codex/images/edits

Authorization: Bearer <tokens.access_token>
ChatGPT-Account-ID: <tokens.account_id>
Content-Type: application/json

{ "model": "gpt-image-2", "prompt": "...", "background": "opaque",
  "quality": "auto", "size": "auto" }

Authentication reads ~/.codex/auth.json — the file codex login writes. Your OPENAI_API_KEY is never touched. When the access token is about to expire, the refresh_token from the same file is exchanged for a fresh one and written back atomically (temp file + rename), so Codex CLI and this tool can share one login.

Install

git clone https://github.com/xurunxin/codex-img-cli.git
cd codex-img-cli
npm link          # puts `codex-img` on your PATH
npm test          # 20 unit tests, no network access required

Prerequisite: run codex login on this machine, with an account that has a ChatGPT subscription.

Prefer not to install it? node bin/codex-img.mjs ... works exactly the same.

npm link writes the shim into the npm global directory. Under nvm-windows that is the version directory (…\nvm\installs\<version>\), which is not on PATH and disappears when you switch Node versions. Drop a small wrapper into a directory that is on PATH:

@echo off
setlocal
set "CODEX_IMG_ENTRY=<repo>\bin\codex-img.mjs"
set "CODEX_IMG_NODE=%LOCALAPPDATA%\Author Software\nvm\.nodejs\node.exe"
if not exist "%CODEX_IMG_NODE%" set "CODEX_IMG_NODE=node"
"%CODEX_IMG_NODE%" "%CODEX_IMG_ENTRY%" %*
exit /b %errorlevel%

Save it as %USERPROFILE%\.local\bin\codex-img.cmd, then check with where codex-img.

Quick start

codex-img auth                        # check the login — offline, no quota
codex-img gen --prompt "a cozy alpine cabin at dawn" --out cabin.png
codex-img edit --image cabin.png \
  --prompt "replace the background with a warm sunset, keep the cabin unchanged" \
  --out sunset.png

CLI reference

Common options:

Command-specific: gen --n <count>, edit --image <file> (repeatable, max 5), models --models <a,b,c>.

Help

Every command carries its own help text, so an agent can learn the tool from the tool itself:

codex-img                    # overview: command table + notes
codex-img help gen           # full reference for one command
codex-img gen --help         # same thing
codex-img --version

Each command's help lists its required arguments, every option, runnable examples, and the behaviour that is easy to get wrong — for example that the endpoint ignores model, or that edit takes at most five reference images. An unknown command exits with code 2 and lists the valid commands.

Multiple images

--n requests more than one image: the first is written to --out, the rest to <out>-2.png, <out>-3.png, …

codex-img gen --prompt "four variations of a brass compass" --n 4 --out compass.png

MCP

The mcp command speaks JSON-RPC 2.0 over stdin/stdout. Any MCP client that speaks stdio can use it.

{
  "mcpServers": {
    "codex-img": {
      "command": "node",
      "args": ["/absolute/path/to/codex-img-cli/bin/codex-img.mjs", "mcp"]
    }
  }
}

With Claude Code:

claude mcp add codex-img -- node /absolute/path/to/codex-img-cli/bin/codex-img.mjs mcp

Two tools are exposed:

The tool descriptions spell out how to write the prompt, why out_path should always be explicit, and that model and size are ignored by this endpoint — so an agent calls it correctly without any extra documentation.

The same request, both ways:

What the endpoint really honours

OpenAI shipped GPT-Image-2.5 on 2026-09-08, split on the API side into gpt-image-2.5-flare (fast) and gpt-image-2.5-sunburst (precise). On this subscription channel you cannot pick between them.

codex-img models probes it first-hand — measured on a Pro subscription:

A model id that does not exist still returns 200, so the endpoint ignores the model field outright. size is ignored too: asking for 1024x1024 comes back as 1254x1254 or 1448x1086, not even satisfying the public Images API rule that side lengths be multiples of 16.

That also explains why openai/codex still hardcodes const IMAGE_MODEL: &str = "gpt-image-2" and yet delivers 2.5 quality: the backend changed, the frontend identifier did not.

Conclusion: choosing between Flare and Sunburst requires an official API key against api.openai.com. On the subscription channel, you get whatever the backend serves.

Requirements and limits

• Needs a ChatGPT subscription and codex login on the same machine.

• This calls an undocumented internal endpoint that is not part of the OpenAI developer documentation. It can change or disappear at any time.

• Using subscription credentials from a non-official client violates the OpenAI terms of service. Self-use is your own call; do not redistribute it or resell access.

• Image generation draws from a quota pool separate from chat (limit_id == "image_gen" in the Codex source).

• Codex rotates refresh tokens. If Codex CLI refreshes at the same moment, you can hit "refresh token already used" — run codex login once and retry.

• Output PNGs carry C2PA metadata and an invisible watermark, same as anything produced by ChatGPT or Codex.

Development

npm test          # node:test, no network, no dependencies
npm link          # run the CLI from your working tree

Layout:

bin/codex-img.mjs   executable entry point
src/cli.mjs         argument parsing and command dispatch
src/help.mjs        the command registry and all help text
src/client.mjs      endpoint calls, base64 payloads, file writing
src/auth.mjs        credential file, token refresh, atomic write
src/mcp.mjs         MCP stdio server and tool schemas
src/version.mjs     version, read from package.json

CI runs the suite on Linux, macOS and Windows against Node 20, 22 and 24.

License

MIT — see LICENSE.

Related work

Independent implementations of the same call, useful as cross-checks:

• headroomlabs-ai/headroom — Python

• caozhiyuan/copilot-api — TypeScript

• kittors/CliRelay — Go, also records the "model field is ignored" finding

• NomaDamas/CozyClay — Node

• NousResearch/hermes-agent — Hermes, with a built-in openai-codex image provider

If you would rather not maintain your own code, Hermes already wraps this and can expose OAuth providers as an OpenAI-compatible endpoint via hermes proxy.