# gpt-image CLI

> A local CLI for OpenAI-compatible image relay APIs, with an optional authenticated remote MCP connector. Download pages distribute software and documentation without collecting API keys.

## Installation

- [Agent auto-install instructions](https://img.zulanhongdan.net/install-agent.md): execute this guide when the user asks you to install gpt-image in their current Agent; includes per-host CLI setup, verification and remote MCP instructions.
- Requires Node.js 22+ and npm; macOS, Windows, and Linux.
- Install: `npm install -g https://img.zulanhongdan.net/downloads/gpt-image-0.1.0.tgz`
- [Shell installer](https://img.zulanhongdan.net/install.sh)
- [PowerShell installer](https://img.zulanhongdan.net/install.ps1)
- [Checksums](https://img.zulanhongdan.net/downloads/SHA256SUMS)

## Agent integration

- [CLI Skill source](https://img.zulanhongdan.net/skill.md)
- [CLI Skill ZIP](https://img.zulanhongdan.net/downloads/gpt-image-skill.zip): requires CLI execution in the Agent's runtime.
- [Remote MCP Skill source](https://img.zulanhongdan.net/remote-skill.md)
- [Remote MCP Skill ZIP](https://img.zulanhongdan.net/downloads/gpt-image-remote-skill.zip): use this with Doubao and other remote-only connectors.
- [Agent setup guide](https://img.zulanhongdan.net/#agents)
- `gpt-image setup --agent codex|claude|cursor|workbuddy|doubao|universal`
- Use `--dry-run` to inspect installation locations. Installing a Skill does not verify the host runtime or tool permissions.
- Doubao CLI setup exports a CLI-oriented Skill and applies only to shell-capable task environments. Recommended Doubao connection: add a custom remote MCP connector, URL `https://img.zulanhongdan.net/mcp`, transport HTTP (Streamable HTTP), custom header `Authorization: Bearer <YOUR_RELAY_API_KEY>`. Optionally import the separate remote MCP Skill ZIP; do not use the CLI Skill for a remote-only environment.
- Save and enable the connector, then ask the Agent to list its tools before generating an image. No local terminal is required for the remote connector.

## Usage

- [Configuration](https://img.zulanhongdan.net/#configuration)
- Defaults: relay base URL `https://s.zulanhongdan.net/v1`, image model `gpt-image-2.5-flare`.
- `gpt-image configure`: enter the API key locally using a hidden input. Use `--base-url` and `--model` to select a different compatible relay/model.
- `gpt-image configure --api-key-stdin`: supply the key over stdin; never put real keys in Skill files or command examples.
- `gpt-image schema`: inspect command contracts before calling.
- `gpt-image generate --prompt "description" --out ./output.png --json`
- `gpt-image edit --image ./input.png --prompt "description" --out ./edited.png --json`
- `--prompt-file` supports long prompts.
- `gpt-image doctor --agents`: inspect local Agent integration.
- `gpt-image doctor --network`: check configured API connectivity.
- [Outputs and history](https://img.zulanhongdan.net/#outputs)
- [MCP integration](https://img.zulanhongdan.net/#mcp): remote Streamable HTTP at `https://img.zulanhongdan.net/mcp`; local stdio via `gpt-image mcp --transport stdio`.
- Remote MCP requires the caller's relay API key in `Authorization: Bearer <YOUR_RELAY_API_KEY>`. It forwards requests only to `https://s.zulanhongdan.net/v1`; no shared server image-generation key is provided.
- Remote image edit accepts Base64 input images. Maximum HTTP request body is 30 MB including Base64 expansion.
- [Troubleshooting](https://img.zulanhongdan.net/#troubleshooting)
- [Data and credentials](https://img.zulanhongdan.net/#privacy)

## Compatibility boundaries

The adapter targets OpenAI-compatible `/images/generations` and `/images/edits` endpoints. Actual model and parameter support depend on the selected relay. No automatic fallback to another image provider. No automatic resubmission of image-generation requests when completion is uncertain. Verify that real output files exist before reporting success.

## Remote data handling

Remote MCP receives the caller's key in the authorization header and uses it in memory for forwarding; keys are not persisted. Prompts and reference images pass through this server to the fixed relay. Generated files are retained for up to 24 hours and returned through unguessable result links. Anyone holding a result link can access it without login: these are unlisted bearer links, not authenticated private storage. Download results before expiry. Local CLI/stdio requests go directly to the configured relay rather than through this remote MCP service.