genmedia CLI

genmedia is a command-line tool that gives any terminal, script, or AI agent direct access to fal’s 1,000+ models. In a terminal it prints a compact human-readable view; when its output is piped or --json is passed, every command emits structured JSON. While the MCP server is the best fit for assistants that speak the Model Context Protocol, genmedia needs nothing but a shell — so it also works in CI/CD pipelines, shell scripts, and agents driven purely by shell commands.

This is not the fal CLI. For deploying and managing your own fal applications — fal deploy, fal run, fal apps — see the CLI Reference.

Installation

Linux and macOS
Windows

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

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

This installs the release binary into ~/.genmedia and puts genmedia on your PATH.

genmedia requires a fal API key. If you don’t have one yet, create one here.

Quick Start

Set your API key

export FAL_KEY="your-api-key-here"

Or run genmedia setup to save it encrypted to your local config.

Find a model

genmedia models "image generation"

Generate an image

genmedia run fal-ai/flux/schnell --prompt "a mountain lake at sunset"

Commands

genmedia covers configuration, model discovery, execution, file uploads, documentation search, and agent onboarding. Run genmedia --help --json for the complete machine-readable command list.

setup

Interactive wizard that configures your API key (saved encrypted locally), .env auto-loading, default output mode, and automatic updates.

genmedia setup

For agents and CI, configure it without prompts. Every flag is optional and omitted fields keep their current values, so repeated invocations are idempotent.

genmedia setup --non-interactive --api-key "$FAL_KEY"
genmedia setup --non-interactive --output-format json --no-auto-load-env

Options:

Flag	Description
`--non-interactive`, `-y`	Skip all prompts. Required when there is no TTY.
`--api-key <key>`	API key to save. Pass `""` to clear the saved key.
`--no-save-key`	With `--api-key`, don’t persist the key — use `FAL_KEY` at runtime instead.
`--output-format <auto\|json\|standard>`	Default output mode.
`--auto-load-env` / `--no-auto-load-env`	Toggle auto-loading `FAL_KEY` from a project `.env`.
`--auto-update` / `--no-auto-update`	Toggle background update checks.

models

Search and inspect fal’s catalog. Pass a query, a category filter, or both. When you give a query without --category, genmedia classifies it and applies an inferred category for you.

# Search by keyword
genmedia models "video generation"

# Filter by category
genmedia models --category text-to-image

# Limit results
genmedia models "upscale" --limit 5

# Fetch specific models by ID
genmedia models --endpoint_id fal-ai/flux/dev,fal-ai/flux/schnell

Options:

Flag	Description
`--category`	Filter by category, e.g. `text-to-image`, `image-to-video`, `text-to-speech`, and more
`--status`	`active` (default), `deprecated`, or `all`
`--limit`	Max results (default: 20)
`--cursor`	Pagination cursor from a previous response
`--endpoint_id`	Fetch specific models by ID — comma-separated or repeated
`--expand`	Expand additional fields: `openapi-3.0`, `enterprise_status`

schema

Get the full input/output parameters for any model. Use this before run to see what options are available.

genmedia schema fal-ai/flux/dev

# Full OpenAPI JSON
genmedia schema fal-ai/flux/dev --format openapi

Returns all parameters with types, descriptions, defaults, and which are required.

run

Run any fal model. By default, submits to the queue and waits for the result.

# Generate an image
genmedia run fal-ai/flux/dev --prompt "a futuristic cityscape" --image_size landscape_16_9

# Save the output files to disk
genmedia run fal-ai/flux/dev --prompt "a cat" --download

# Submit without waiting
genmedia run fal-ai/kling-video/v3/pro/text-to-video \
  --prompt "a cat playing piano" --async

Options:

Flag	Description
`--<param>`	Any model input parameter, e.g. `--prompt`, `--num_images`
`--async`	Submit to queue and return the request ID immediately
`--logs`	Stream logs while the model runs (terminal mode only)
`--download [template]`	Download every media URL in the result. Accepts a path or a template with `{index}`, `{name}`, `{ext}`, `{request_id}`. Written paths appear in JSON output under `downloaded_files`.

Model parameters are passed as --key value flags, and the key names match the model’s input schema exactly. To see a specific model’s parameters rendered as CLI flags:

genmedia run fal-ai/flux/dev --help

You can also skip the endpoint ID entirely — pass a bare prompt and genmedia picks a suitable model for you:

genmedia run "a golden retriever surfing a wave"

status

Check the status of an async job, fetch the result, or cancel it.

# Check status
genmedia status fal-ai/flux/dev abc123-request-id

# Get the result
genmedia status fal-ai/flux/dev abc123-request-id --result

# Cancel a job
genmedia status fal-ai/flux/dev abc123-request-id --cancel

Options:

Flag	Description
`--result`	Fetch the completed result
`--logs`	Show logs verbosely
`--cancel`	Cancel the queued job
`--download [template]`	Same as on `run`. Implies `--result`.

upload

Upload a local file or URL to fal’s CDN. Returns a URL you can pass to any model.

# Upload a local file
genmedia upload ./my-image.png

# Upload from URL
genmedia upload https://example.com/photo.jpg

Returns a cdn_url like https://v3b.fal.media/files/b/... that works with any model parameter that accepts a URL.

pricing

Get the cost of running a model.

genmedia pricing fal-ai/flux/dev

docs

Search the fal documentation for guides, API references, and examples.

genmedia docs "how to use webhooks"

gallery

Every successful genmedia run records its outputs into a per-session, self-contained HTML page under ~/.genmedia/gallery/sessions/, aggregating every image, video, audio, and 3D asset produced in one agent session into a filterable grid.

# Print the current session's gallery URL
genmedia gallery

# Open it in your browser
genmedia gallery open current

# List every recorded session
genmedia gallery list

Set GENMEDIA_NO_GALLERY=1 to disable recording.

init and skills

Install agent skills so coding agents in a project know how to use genmedia without reading --help first.

# Install the default genmedia skill bundle
genmedia init

# Browse and manage the skill registry
genmedia skills list
genmedia skills install genmedia

init writes into .agents/skills/ if the project has an .agents/ directory, otherwise .claude/skills/. Commit that directory so teammates and other agents get the same context.

version and update

genmedia version

# Download and swap in the latest release
genmedia update

# Only check, don't download
genmedia update --check

Automatic background update checks are on by default. Set GENMEDIA_NO_UPDATE=1 to disable them; genmedia update still works.

Output and JSON

Output adapts to where it’s going:

In a terminal — a compact, human-readable view.
Piped, redirected, or with --json — structured JSON.

genmedia models "text to video" --json | jq '.models[]'

To make JSON the default everywhere, run genmedia setup --non-interactive --output-format json. Errors are written to stderr as JSON with a non-zero exit code:

{
  "error": "Model not found: fal-ai/nonexistent"
}

Some errors carry an additional details object with context such as request_id, status, or validation_errors. Success responses vary by command but always include the relevant data as a JSON object.

Examples

End-to-end image generation

# 1. Find a model
genmedia models "fast image generation" --limit 3

# 2. Check what parameters it accepts
genmedia schema fal-ai/flux/schnell

# 3. Generate an image and save it locally
genmedia run fal-ai/flux/schnell \
  --prompt "a photorealistic sunset over the ocean" \
  --image_size landscape_16_9 \
  --num_images 1 \
  --download

Video generation (async)

# 1. Submit a video generation job
genmedia run fal-ai/kling-video/v3/pro/text-to-video \
  --prompt "a cinematic drone shot over a mountain range" \
  --duration 5 \
  --async

# Returns: { "request_id": "abc123..." }

# 2. Check status
genmedia status fal-ai/kling-video/v3/pro/text-to-video abc123

# 3. Get the result when complete
genmedia status fal-ai/kling-video/v3/pro/text-to-video abc123 --result

Image-to-video with file upload

# 1. Upload your image
genmedia upload ./my-photo.jpg
# Returns: { "cdn_url": "https://v3b.fal.media/files/b/..." }

# 2. Use the CDN URL as input
genmedia run fal-ai/kling-video/v3/pro/image-to-video \
  --prompt "gentle camera zoom, leaves blowing in wind" \
  --start_image_url "https://v3b.fal.media/files/b/..." \
  --async

Parameter names are per-endpoint. This endpoint takes start_image_url (plus an optional end_image_url), not image_url. Run genmedia run <endpoint_id> --help to see exactly what a model accepts.

Use with AI agents

The fastest way to teach an agent about genmedia is to install the skill bundle in your project:

genmedia init

For agents that build their own tool configuration, ask genmedia to describe itself:

genmedia --help --json

This returns a structured object with the CLI’s name, version, install info, expected environment variables, and a commands map giving each command’s description, usage, arguments, options, and output fields — everything an agent needs to discover capabilities without guessing.

Next Steps

AI Tools

Connect MCP-compatible assistants to the full fal platform

Get Your API Key

Create and manage the keys genmedia authenticates with

Async Inference

How async submission, status polling, and webhooks work

GitHub Repository

View the source code, report issues, or contribute

Setting Up

Model APIs

Serverless

Compute

Organizations

genmedia CLI

Installation

Quick Start

Commands

setup

models

schema

run

status

upload

pricing

docs

gallery

init and skills

version and update

Output and JSON

Examples

End-to-end image generation

Video generation (async)

Image-to-video with file upload

Use with AI agents

Next Steps

AI Tools

Get Your API Key

Async Inference

GitHub Repository

​Installation

​Quick Start

​Commands

​setup

​models

​schema

​run

​status

​upload

​pricing

​docs

​gallery

​init and skills

​version and update

​Output and JSON

​Examples

​End-to-end image generation

​Video generation (async)

​Image-to-video with file upload

​Use with AI agents

​Next Steps

AI Tools

Get Your API Key

Async Inference

GitHub Repository

Installation

Quick Start

Commands

setup

models

schema

run

status

upload

pricing

docs

gallery

init and skills

version and update

Output and JSON

Examples

End-to-end image generation

Video generation (async)

Image-to-video with file upload

Use with AI agents

Next Steps