# imageflare

[![PyPI version](https://img.shields.io/pypi/v/imageflare.svg)](https://pypi.org/project/imageflare/)
[![Python versions](https://img.shields.io/pypi/pyversions/imageflare.svg)](https://pypi.org/project/imageflare/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A command-line tool for generating and editing images using [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) — directly from your terminal, no server required. Works on **Windows, macOS, and Linux**.

## Features

- **Generate** images from text prompts using state-of-the-art AI models
- **Edit** existing images with a text prompt (img2img)
- **Multi-reference** support — supply up to 3 additional reference images for style/content
- **Dynamic model list** — fetches available models live from your Cloudflare account
- **Interactive config wizard** — guided first-run setup for credentials and model selection
- Spinner feedback, seed control, auto-open output, and configurable output path

## Installation

**Requirements:** Python 3.8+ and a [Cloudflare account](https://dash.cloudflare.com) with [Workers AI](https://developers.cloudflare.com/workers-ai/) access (free tier available).

### macOS / Linux

```bash
pip install imageflare
```

### Windows

```powershell
pip install imageflare
```

> **Tip (Windows):** If `imageflare` is not found after installing, your Python Scripts folder may not be on your PATH. Either use `python -m imageflare` as a drop-in replacement, or add the Scripts folder to your PATH:
> - Open **Start → Edit the system environment variables → Environment Variables**
> - Under *User variables*, edit `Path` and add `%APPDATA%\Python\PythonXXX\Scripts`

### Using a virtual environment (recommended)

<details>
<summary>macOS / Linux</summary>

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install imageflare
```
</details>

<details>
<summary>Windows (Command Prompt)</summary>

```cmd
python -m venv .venv
.venv\Scripts\activate.bat
pip install imageflare
```
</details>

<details>
<summary>Windows (PowerShell)</summary>

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install imageflare
```
</details>

## Quick Start

The `imageflare` command works identically on all platforms:

```bash
# Step 1 — configure your credentials (one time)
imageflare config

# Generate an image from a prompt
imageflare generate --prompt "a red fox sitting on a snow-covered log"

# Edit an existing image
imageflare edit photo.jpg --prompt "make it look like a watercolor painting"

# Edit with a style reference image
imageflare edit photo.jpg --prompt "apply this style" --ref style.png

# Save to a specific path and open immediately after
imageflare generate --prompt "sunset over mountains" --output sunset.png --open
```

## Configuration

Credentials are stored in a config file. The location varies by OS:

| OS | Config file location |
|---|---|
| **Linux** | `~/.config/imageflare/config` |
| **macOS** | `~/.config/imageflare/config` |
| **Windows** | `%APPDATA%\imageflare\config` |

```bash
imageflare config                     # interactive setup wizard
imageflare config show                # view current settings
imageflare config models              # list available AI models
imageflare config set --account-id YOUR_ID --api-token YOUR_TOKEN
imageflare config set --model "@cf/black-forest-labs/flux-1-schnell"
```

**Getting credentials:**

| Credential | Where to find it |
|---|---|
| **Account ID** | [Cloudflare dashboard](https://dash.cloudflare.com) → right sidebar of any page |
| **API Token** | *My Profile → API Tokens → Create Token* — select the **Workers AI** template or grant `Workers AI: Read` permission |

## Commands

### `imageflare generate`

Generate an image from a text prompt.

```
Usage: imageflare generate [OPTIONS]

Options:
  -p, --prompt TEXT     Description of the image to generate  [required]
  -m, --model TEXT      Cloudflare Workers AI model ID
      --width INTEGER   Output width in pixels  [default: 1024]
      --height INTEGER  Output height in pixels  [default: 1024]
      --seed INTEGER    Random seed for reproducible results
  -o, --output PATH     Output file path  [default: imageflare_<timestamp>.png]
      --open            Open the saved image automatically
  -h, --help            Show this message and exit
```

### `imageflare edit`

Edit an existing image using a text prompt.

```
Usage: imageflare edit IMAGE_PATH [OPTIONS]

Arguments:
  IMAGE_PATH            Path to the input image  [required]

Options:
  -p, --prompt TEXT     Editing instruction  [required]
  -r, --ref PATH        Additional reference image (repeatable, up to 3)
  -m, --model TEXT      Cloudflare Workers AI model ID
      --width INTEGER   Output width in pixels  [default: 1024]
      --height INTEGER  Output height in pixels  [default: 1024]
      --seed INTEGER    Random seed for reproducible results
  -o, --output PATH     Output file path  [default: imageflare_<timestamp>.png]
      --open            Open the saved image automatically
  -h, --help            Show this message and exit
```

**Windows path tip:** Use forward slashes or wrap paths in quotes if they contain spaces:

```powershell
imageflare edit "C:\Users\You\Pictures\photo.jpg" --prompt "turn it into a sketch"
```

### `imageflare config`

```
Usage: imageflare config [COMMAND]

Commands:
  (no command)   Launch the interactive setup wizard
  show           Print current credentials and settings
  models         List all available Workers AI image models
  set            Update one or more settings non-interactively

Options for `config set`:
  --account-id TEXT   Cloudflare account ID
  --api-token TEXT    Cloudflare API token
  --model TEXT        Default model ID
```

## Models

`imageflare` works with any [Cloudflare Workers AI text-to-image model](https://developers.cloudflare.com/workers-ai/models/#text-to-image). Once credentials are configured, the live model list is fetched automatically from the API.

Run `imageflare config models` to see everything available on your account.

**Default model:** `@cf/black-forest-labs/flux-2-klein-4b`

## How It Works

1. You provide a prompt (and optionally an input image for editing)
2. `imageflare` sends the request to the [Cloudflare Workers AI REST API](https://developers.cloudflare.com/api/resources/ai/methods/run/) using your credentials
3. The generated image is returned and saved locally — no intermediate servers, no data retained

## Contributing

Issues and pull requests are welcome at [github.com/Sallytion/Imageflare](https://github.com/Sallytion/Imageflare).

## License

[MIT](https://opensource.org/licenses/MIT)

