genmedia

Agent-first CLI for fal.ai — search, run, and manage 1200+ model endpoints.

Works great for humans in a terminal and equally well for AI agents via shell commands. In a TTY, commands display a lightweight pretty view; when piped or called with --json, they emit structured JSON. No MCP required.

Install

For Linux and macOS:

curl https://genmedia.sh/install -fsS | bash

For Windows:

irm https://genmedia.sh/install.ps1 | iex

Setup

genmedia setup

Interactive wizard that configures:

• API key — saved encrypted to your local config (or skip and use FAL_KEY in your environment)
• Auto-load .env — automatically load FAL_KEY and related vars from a project .env file
• Output mode — auto (pretty in TTY, JSON when piped), json (always structured), or standard (always human-readable)
• Automatic updates — check for new versions in the background and swap in on next launch (default: on; set GENMEDIA_NO_UPDATE=1 to disable)

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

To skip the wizard, set the key in your environment:

export FAL_KEY=your_fal_api_key

Commands

models — Search and inspect models

genmedia models "text to video"
genmedia models "flux" --category text-to-image
genmedia models --category text-to-speech --limit 5
genmedia models --status all                                      # include deprecated
genmedia models --endpoint_id fal-ai/flux/dev,fal-ai/flux/schnell # fetch specific models
genmedia models --endpoint_id fal-ai/flux/dev --expand openapi-3.0
genmedia models "flux" --cursor                            # next page

schema — Inspect model inputs/outputs

genmedia schema fal-ai/flux/dev
genmedia schema fal-ai/flux/dev --format openapi

run — Run a model

genmedia run fal-ai/flux/dev --prompt "a cat on the moon"
genmedia run fal-ai/flux/dev --prompt "a cat" --num_images 2
genmedia run fal-ai/flux/dev --prompt "a cat" --logs
genmedia run fal-ai/veo3.1 --prompt "a dog running" --async
genmedia run fal-ai/flux/dev --help    # introspect model inputs as CLI help

Any model input parameter can be passed as a --flag value pair. Run genmedia run --help to see a model's accepted parameters rendered as CLI flags, or genmedia schema for the same info as structured JSON.

status — Check an async job

genmedia status fal-ai/veo3.1 
genmedia status fal-ai/veo3.1  --result
genmedia status fal-ai/veo3.1  --logs
genmedia status fal-ai/veo3.1  --cancel

upload — Upload files to fal.ai CDN

genmedia upload ./photo.jpg
genmedia upload https://example.com/image.png

Accepts a local file path or a remote URL. Returns a CDN URL you can use as model input.

pricing — Check model pricing

genmedia pricing fal-ai/flux/dev

docs — Search documentation

genmedia docs "how to use LoRA"
genmedia docs "webhook callbacks"

Searches fal.ai documentation, guides, and API references.

version — Show version

genmedia version

Shows the current version and flags any known update (populated by the background checker).

update — Check for and apply updates

genmedia update              # download and swap in the latest release
genmedia update --check      # only check, don't download
genmedia update --force      # reinstall even if already on the latest

When automatic updates are enabled (default), every TTY invocation may trigger a rate-limited (1/hour) background check that stages the next release. The next genmedia launch atomically swaps it in. Set GENMEDIA_NO_UPDATE=1 to disable all background checks; the manual update command still works.

init — Install the default genmedia skill bundle

genmedia init
genmedia init --force   # overwrite existing files

Installs the default genmedia skill bundle:

The bundle is installed into .agents/skills/ in the current directory and linked into .claude/skills/ by default.

After running init, compatible agent sessions in that project can use the installed skills without needing to call --help. Commit .agents/ and the generated links so teammates and other agents get the same context.

skills — Manage installed agent skills

genmedia skills list
genmedia skills install genmedia
genmedia skills update
genmedia skills remove genmedia

Installs, updates, lists, and removes agent skills from the genmedia registry.

Agent-first design

All commands output structured JSON when piped or called with --json:

genmedia run fal-ai/flux/dev --prompt "a cat" --json
genmedia models "text to video" --json | jq '.models[]'

To get a machine-readable description of all commands for use in a system prompt or agent context:

genmedia --help --json

This returns a full schema of every command, its arguments, and options. Agents that don't support MCP (Codex, Gemini CLI, etc.) can use fal.ai through genmedia via standard shell commands.

License

MIT