@howells/falcon

Falcon

CLI for generating images with fal.ai

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

Installation

Homebrew (Recommended)

brew tap howells/tap
brew install falcon

bunx (No install)

bunx @howells/falcon "your prompt"

Manual Install

Requires Bun runtime.

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

Configuration

Set your fal.ai API key:

export FAL_KEY="your-api-key"

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

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

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

Config Options

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

Generate Images

# 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

Edit Images

# Edit an existing image with a prompt
falcon "add a rainbow in the sky" -e ./photo.png

Post-Processing

# 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

Interactive Studio

Run falcon without arguments to launch the interactive terminal UI:

falcon

Models

Generation Models

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

Utility Models

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>      Model: gpt, banana, gemini, gemini3
  -e, --edit <file>        Edit an existing image with prompt
  -a, --aspect <ratio>     Aspect ratio (see below)
  -r, --resolution <res>   Resolution: 1K, 2K, 4K
  -o, --output <file>      Output filename
  -n, --num <count>        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 <factor>         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

Aspect Ratios

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