How to Use Image Input with Codex CLI

Codex CLI's multimodal capabilities allow you to attach screenshots, design mockups, and diagrams alongside your text prompts. This enables powerful design-to-code workflows where you can turn visual specifications into working implementations.

Understanding Image Input

The --image (or -i) flag allows you to attach one or more image files to your Codex prompt. The AI model processes both the visual content and your text instructions to generate appropriate code.

Supported formats:

Unsupported formats: BMP, TIFF, SVG, and HEIC are not supported. Convert these to PNG or JPEG before use.

Basic Usage

Attaching a Single Image

The simplest way to use image input is with the --image flag:

codex "Implement this UI component in React" --image ./mockup.png

Or using the short form:

codex "Build this layout with Tailwind CSS" -i ./design.png

Attaching Multiple Images

When you need to provide multiple reference images, use comma separation:

codex "Create a responsive layout that matches these designs" --image ./desktop.png,./mobile.png

Or repeat the flag:

codex -i ./current-state.png -i ./desired-state.png "Update the styling to match the second screenshot"

Using with the exec Command

For non-interactive execution:

codex exec --image ./error-screenshot.png "Fix the error shown in this screenshot"

Design-to-Code Workflow

The most powerful use case for image input is converting design mockups into working code. Here is a structured workflow for best results.

Step 1: Prepare Your Design File

Save your design mockup, screenshot, or wireframe locally:

# Example directory structure
project/
├── specs/
│   ├── dashboard-mockup.png
│   ├── mobile-view.png
│   └── component-details.png
└── src/

Step 2: Craft a Detailed Prompt

The image provides visual requirements, but you must specify implementation constraints:

codex "Create a new dashboard based on this image.

Constraints:
- Use React, Vite, and Tailwind CSS
- Write the code in TypeScript
- Match spacing, typography, and layout as closely as possible

Deliverables:
- A new route/page that renders the UI
- Any small components needed
- Instructions to run it locally" --image ./specs/dashboard-mockup.png

Step 3: Include Behavioral Details

For best results, specify any non-obvious behavior that the visual does not convey:

codex "Build this form component. Additional requirements:
- Email field should validate on blur
- Submit button disabled until form is valid
- Show inline error messages below each field
- Add loading spinner during submission
- Keyboard navigation: Tab between fields, Enter to submit" --image ./form-design.png

Step 4: Verify the Output

After Codex generates the code, request verification:

codex "Start the dev server and tell me the exact URL to view the dashboard"

Practical Examples

Example 1: Error Message Analysis

When debugging, screenshot the error and let Codex analyze it:

codex "What is causing this error and how do I fix it?" --image ./error-screenshot.png

Example 2: UI Component Recreation

Recreate a component from another site or application:

codex "Recreate this navigation component using Next.js and Tailwind. Include:
- Responsive mobile menu
- Active state highlighting
- Smooth transitions" --image ./nav-reference.png

Example 3: Code Review with Visual Context

Compare current implementation against the design:

codex -i ./design-spec.png -i ./current-screenshot.png "Compare these two images. The first is the design spec, the second is our current implementation. List the differences and fix them."

Example 4: Dashboard Layout Implementation

Build a complete dashboard from a mockup:

codex "Build a deployment status dashboard that looks like this screenshot.

Tech stack: React, TypeScript, Tailwind CSS
Features:
- Real-time status indicators
- Sortable table columns
- Filter by environment (production, staging, development)
- Export to CSV button" --image ./dashboard-mockup.png

Platform-Specific Notes

macOS

Clipboard pasting:

• Use Ctrl+V (not Cmd+V) to paste images from clipboard
• Screenshots captured with Cmd+Ctrl+Shift+4 require Ctrl+V to paste
• Copying image files from Finder works with both Cmd+V and Ctrl+V

Drag and drop:

Drag image files directly into the terminal to attach them to your prompt.

Screenshot workflow:

# Take screenshot to clipboard
# Press Cmd+Ctrl+Shift+4, select region

# Launch Codex and paste
codex
# Press Ctrl+V to paste the screenshot
# Type your prompt

Windows

Native Windows Terminal:

• Use Ctrl+V to paste from clipboard
• Screenshots taken with Win+Shift+S may require saving to a file first

Recommended approach:

1. Save screenshots to a file using Win+Shift+S and clicking "Save"
2. Reference the file path in your Codex command

codex "Analyze this error" --image C:\Users\YourName\Screenshots\error.png

WSL users:

If running Codex in WSL, access Windows screenshots through the mounted drive:

codex "Fix this bug" --image /mnt/c/Users/YourName/Screenshots/error.png

Linux

Wayland:

There is a known issue where Ctrl+V may not show a visual placeholder even when the image is successfully read. The image is still attached; continue with your prompt.

X11:

Standard Ctrl+V pasting works as expected.

Taking screenshots:

# Using gnome-screenshot
gnome-screenshot -a -f /tmp/screenshot.png

# Then use with Codex
codex "Implement this UI" --image /tmp/screenshot.png

Interactive Mode Image Pasting

When running Codex interactively (without a prompt on the command line), you can paste images directly:

1. Launch Codex:

   codex
   

   Copy

2. Copy an image to your clipboard (screenshot, copy from browser, etc.)

3. Press Ctrl+V to paste the image

4. Type your prompt and press Enter

This workflow is useful for quick iterations where you are taking screenshots and immediately asking questions about them.

Best Practices

Image Preparation

1. Crop to relevant content - Remove unnecessary UI chrome or desktop background
2. Use appropriate resolution - 1920x1080 or smaller is typically sufficient
3. Keep file size under 5MB - Compress if necessary
4. Use PNG for UI elements - Preserves text clarity and supports transparency

Prompt Engineering

1. Specify the tech stack - Framework, styling approach, language preferences
2. Include behavioral requirements - Hover states, validation, keyboard interactions
3. Mention existing patterns - Reference your project's component library or design system
4. Request specific deliverables - Files to create, structure expectations

Verification

1. Ask Codex to run the code - Have it start dev servers and provide URLs
2. Request visual comparison - Ask it to verify the output matches the mockup
3. Test edge cases - Different screen sizes, empty states, error states

Limitations

• No autonomous file inspection - Codex cannot independently browse and analyze image files in your directory. You must explicitly attach images via the --image flag or paste them.
• Single session context - Images attached in one prompt are not automatically available in follow-up prompts unless re-attached.
• Complex animations - GIF analysis uses only the first frame; describe animations in text.
• Handwritten content - OCR accuracy varies; typed or printed text works best.

Troubleshooting

Image Not Recognized

If Codex does not seem to process your image:

1. Verify the file format is supported (PNG, JPEG, GIF, WebP)
2. Check file size is under 5MB
3. Ensure the file path is correct and accessible
4. Try saving and re-attaching rather than pasting from clipboard

Paste Not Working

macOS: Use Ctrl+V instead of Cmd+V

Windows: Save the screenshot to a file and use --image path

Linux (Wayland): The image may be attached even without visual confirmation

Poor Code Quality from Mockup

If the generated code does not match your design well:

1. Add more detailed text instructions about spacing, colors, and typography
2. Provide multiple reference images (desktop + mobile views)
3. Specify exact pixel values or Tailwind classes if you have preferences
4. Break complex UIs into smaller components and generate them individually

Next Steps

• Learn about other Codex CLI features
• Explore Codex workflows for more advanced use cases
• Read our guide on installing Codex CLI if you have not set it up yet
• Compare with Claude Code for complex multi-file refactoring tasks