---
canonical: "https://agi-labo.com/en/tools/cockpit/docs/cockpit-cli/reference/gen-image"
title: "cockpit gen-image"
description: "Generated reference for cockpit gen-image, including its syntax, options, results, and constraints from the canonical cockpit CLI source."
section: "Reference"
order: 112
pageType: reference
lastVerifiedVersion: 4.61.0
lastVerifiedAt: "2026-08-27"
draft: false
surfaces:
  - cli
operatingSystems:
  - windows
  - macos
  - linux
plans:
  - guest
  - member
navigation: false
---

This reference is generated from the same canonical source distributed as cockpit CLI help. See [Cockpit CLI](/en/tools/cockpit/docs/cockpit-cli) for concepts and safe operating guidance.

Usage: `cockpit gen-image --prompt <text> --out <path> [options]`

Generate one image with an external provider and save it to `--out` (`.png` or `.jpg`). Self-contained: any agent can call this, including agents with no native image tool. Uses the provider's own credentials. When `--provider` is omitted, uses `codex` with `gpt-image-2`.

```bash
cat prompt.txt | cockpit gen-image --stdin --out image.png --json
cockpit gen-image --provider codex --model gpt-image-2 --prompt "a friendly shiba in soft watercolor, white background" --size 1024x1024 --out image.png --json
cockpit gen-image --provider antigravity --prompt "the same shiba, now wearing a scarf" --reference image.png --size 1024x1024 --out image-2.png --json
cockpit gen-image --provider grok-build --prompt "a cinematic product photo of a brass desk lamp" --size 1536x1024 --out lamp.jpg --json
```

Options:

- `--prompt <text>` — image description (or use `--stdin`)
- `--out <path>` — output image path (required)
- `--provider <name>` — `codex` (default), `antigravity`, or `grok-build`
- `--model <name>` — codex: image model (default `gpt-image-2`); antigravity: `agy` driver model (image backend is fixed)
- `--size <WxH>` — image size, e.g. `1024x1024`, `1536x1024` (default `1024x1024`)
- `--reference <path>` — reference image for style/character consistency (repeatable)
- `--stdin` — read the prompt from stdin
- `--json` — JSON output

Providers:

- `codex` — OpenAI image generation (`gpt-image-2`) via the Codex subscription
- `antigravity` — Google Gemini image backend via the Antigravity free quota; outputs JPG (auto-converted to PNG when `--out` ends in `.png`)
- `grok-build` — xAI Imagine (`grok-imagine-image`) via the Grok Build / SuperGrok subscription; outputs JPG (auto-converted to PNG for `.png` `--out`)

After generating, open the saved file in the side panel when the user needs to inspect it: `cockpit side-panel file image.png --mode preview --json`. For short videos, see `cockpit gen-video help`.