falgen 0.1.1

AI media generation from the terminal — powered by fal.ai

falgen

Open source AI media generation from the terminal.

Install · Usage · Features · Commands · Contributing

---

Generate images, videos, audio, and more - just describe what you want. falgen picks the best model using Artificial Analysis quality rankings, handles the queue, and renders results inline in your terminal.

Install

Recommended - install as an isolated tool (won't pollute your Python environment):

pipx install falgen     # via pipx
uv tool install falgen  # via uv

Quick install - auto-detects the best method:

curl -fsSL https://raw.githubusercontent.com/ilkerzg/falgen/main/install.sh | bash

Other options:

pip install falgen   # standard pip
npx falgen           # run without installing (via npm)

Requires Python 3.11+.

Auth

# Option 1: falgen prompts for your key on first launch
falgen

# Option 2: environment variable
export FALGEN_KEY="your-key-here"
falgen

Get your API key at fal.ai/dashboard/keys. FAL_KEY is also supported. Use /logout to remove a saved key.

Usage

falgen                  # start a new session
falgen -s last          # resume last session
falgen -m openai/gpt-5.4  # use a specific LLM

Then just type what you want:

> a cyberpunk city at sunset, neon reflections on wet streets
> generate a 10s video of ocean waves crashing
> create lofi hip-hop background music, chill vibes
> upscale my photo to 4K

Features

Smart model selection - Ranks models by quality using Artificial Analysis arena ELO ratings. Supports style-specific rankings (portraits, anime, photorealistic, etc.) so you always get the best model for your task.

The agent asks which model to use, ranked by Artificial Analysis ELO ratings, and proceeds based on your choice.

AI tools - The LLM agent has access to:

Tool	Description
best_models	Quality rankings from Artificial Analysis arena
search_models	Search fal.ai's 600+ model catalog
model_info	Input schema, parameters, valid values
generate	Submit jobs, poll status, stream results
ask_user	Interactive choice picker for decisions
get_skill	Domain knowledge (cinematography, prompting, etc.)
get_pricing	Cost per image/minute/character

Tool calls in action - the agent searches models, checks schemas, and submits a generation job with a live loading skeleton.

Generated image rendered inline via chafa. Click to open in your system viewer.

Terminal UI - Built with Textual. Inline media preview via chafa. Five themes: Tokyo Night, Catppuccin, Nord, Gruvbox, Everforest.

Slash commands with autocomplete for quick access to all features.

Input - Multi-line input (Shift+Enter), image paste from clipboard (Ctrl+V), local file path detection and upload, fuzzy-filtered choice menus.

Session management - SQLite persistence, resume previous sessions (/resume), media URLs tracked per session.

Context management - Automatic conversation summarization when approaching context limits.

Commands

Command	Description
/model	Switch LLM
/theme	Switch color theme
/search	Search fal.ai models
/info	Model schema and details
/price	Check pricing
/default	Set default models per category
/resume	Resume a previous session
/compact	Toggle compact mode (hide tool calls)
/usage	Usage and cost
/login	Set API key
/logout	Remove API key
/clear	Clear conversation

Keyboard: Shift+Enter new line · Esc cancel generation · Ctrl+L clear · Ctrl+V paste image · Ctrl+C quit

Preview Dependencies

• chafa - inline image/video/audio previews
• ffmpeg - video thumbnails and audio waveforms
• Optional: pngpaste - clipboard image paste on macOS

The app runs without these, but previews will be unavailable.

Contributing

Open source side project. Contributions, issues, and ideas are welcome.

git clone https://github.com/ilkerzg/falgen
cd falgen
pip install -e .
falgen

Acknowledgements

Model quality rankings powered by Artificial Analysis - independent benchmarks through crowd-sourced blind comparisons.

License

MIT