Falcon

CLI for generating images with fal.ai

---

Supports multiple models, batch generation, upscaling, and background removal.

Installation

$3

``bash
brew tap howells/tap
brew install falcon
`

$3

`bash
bunx @howells/falcon "your prompt"
`

$3

Requires Bun runtime.

`bash
git clone https://github.com/howells/falcon.git
cd falcon
bun install
bun link
`

Configuration

Set your fal.ai API key:

`bash
export FAL_KEY="your-api-key"
`

Or add it to ~/.falcon/config.json:

`json
{
"apiKey": "your-api-key"
}
`

Get your API key at fal.ai/dashboard/keys.

$3

| Option | Default | Description |
|--------|---------|-------------|
| apiKey | - | Your fal.ai API key |
| defaultModel | banana | Default generation model |
| defaultAspect | 1:1 | Default aspect ratio |
| defaultResolution | 2K | Default resolution |
| openAfterGenerate | true | Auto-open images after generation |
| upscaler | clarity | Upscaler model (clarity or crystal) |
| backgroundRemover | rmbg | Background removal model (rmbg or bria) |

You can also create a .falconrc file in any directory to override settings per-project.

Usage

$3

`bash


Basic generation

falcon "a cat sitting on a windowsill at sunset"

Specify model

falcon "cyberpunk cityscape" -m banana

Set aspect ratio and resolution

falcon "mountain landscape" -a 16:9 -r 4K

Generate multiple images

falcon "abstract art" -n 4

Use presets

falcon "book cover design" --cover # Kindle: 2:3, 2K
falcon "profile picture" --square # 1:1
falcon "desktop wallpaper" --landscape # 16:9
falcon "phone wallpaper" --portrait # 2:3

Social media presets

falcon "instagram story" --story # 9:16 (1080×1920)
falcon "insta reel cover" --reel # 9:16
falcon "feed post" --feed # 4:5 (1080×1350)
falcon "blog preview" --og # Open Graph: 16:9

Transparent images (GPT model only)

falcon "logo on transparent background" --transparent -m gpt
`

$3

`bash


Edit an existing image with a prompt


falcon "add a rainbow in the sky" -e ./photo.png
`

$3

`bash


Show last generation info

falcon --last

Generate variations of last image

falcon --vary
falcon --vary -n 4 # 4 variations

Upscale last image

falcon --up
falcon --up --scale 4 # 4x upscale

Remove background from last image

falcon --rmbg
`

$3

Run falcon without arguments to launch the interactive terminal UI:

`bash
falcon
`

Models

$3

All models support image editing with the -e flag.

| Model | Name | Pricing | Features |
|-------|------|---------|----------|
| banana | Nano Banana Pro | $0.15-$0.30/image | Aspect, resolution (default) |
| gpt | GPT Image 1.5 | $0.01-$0.20/image | Variable quality settings |
| gemini | Gemini 2.5 Flash | $0.039/image | Fast, affordable |
| gemini3 | Gemini 3 Pro | $0.15-$0.30/image | Highest quality |

$3

| Model | Name | Use |
|-------|------|-----|
| clarity | Clarity Upscaler | Default upscaler |
| crystal | Crystal Upscaler | Alternative upscaler |
| rmbg | BiRefNet | Background removal |
| bria | Bria RMBG 2.0 | Background removal |

Options Reference

`
Usage: falcon [prompt] [options]

Options:
-m, --model Model: gpt, banana, gemini, gemini3
-e, --edit Edit an existing image with prompt
-a, --aspect Aspect ratio (see below)
-r, --resolution Resolution: 1K, 2K, 4K
-o, --output Output filename
-n, --num Number of images (1-4)
--transparent Transparent PNG (GPT model only)
--no-open Don't auto-open image after generation

Post-processing:
--last Show last generation info
--vary Generate variations of last image
--up Upscale last image
--rmbg Remove background from last image
--scale Upscale factor: 2, 4, 6, 8 (with --up)

Presets:
Format:
--cover Kindle/eBook cover: 2:3, 2K
--square Square: 1:1
--landscape Landscape: 16:9
--portrait Portrait: 2:3

Social Media:
--story Instagram/TikTok Story: 9:16
--reel Instagram Reel: 9:16
--feed Instagram Feed: 4:5
--og Open Graph / social share: 16:9

Devices:
--wallpaper iPhone wallpaper: 9:16, 2K

Cinematic:
--wide Cinematic wide: 21:9
--ultra Ultra-wide banner: 21:9, 2K
`

$3

21:9 | 16:9 | 3:2 | 4:3 | 5:4 | 1:1 | 4:5 | 3:4 | 2:3 | 9:16

Cost Tracking

Falcon tracks your spending automatically:

`
Session: $0.52 | Today: $1.24
`

View your history in ~/.falcon/history.json`.

License

MIT