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.

For Linux and macOS:

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

For Windows:

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

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

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

Every flag is optional — fields you don't pass keep their current values, so repeated invocations are idempotent.

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 <token>                           # next page

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

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 --prompt "a cat" --download                               # save to cwd with source file names
genmedia run fal-ai/flux/dev --prompt "a cat" --num_images 3 --download "./out/{index}.{ext}"
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 <endpoint_id> --help to see a model's accepted parameters rendered as CLI flags, or genmedia schema <endpoint_id> for the same info as structured JSON.

genmedia status fal-ai/veo3.1 <request_id>
genmedia status fal-ai/veo3.1 <request_id> --result
genmedia status fal-ai/veo3.1 <request_id> --logs
genmedia status fal-ai/veo3.1 <request_id> --cancel
genmedia status fal-ai/veo3.1 <request_id> --download ./out/   # implies --result

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.

genmedia pricing fal-ai/flux/dev

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

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

genmedia version

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

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.

Released binaries report anonymous usage analytics (PostHog) to help us prioritize improvements. Each install gets a random UUID stored in ~/.genmedia/config.json; we never collect command arguments, prompts, file paths, API keys, or error messages.

Events:

• command_run — top-level command name, success/failure, duration
• cli_first_run — fired once when the install is first seen
• setup_completed — setup finished successfully
• model_run — run finished, with the model endpoint, success/failure, and duration (no inputs or outputs)
• skills_searched — skills list [query] — the query string and result count
• skills_installed / skills_updated / skills_removed — skill name and status
• update_applied — self-update succeeded, with from/to versions

Caller context: every event also carries the detected calling agent (e.g. claude-code, codex, cursor-agent, gemini-cli, aider), the host terminal (vscode, iterm, warp, …), CI flags (ci, ci_provider, github_actions), TTY status, and a per-process invocation_id so multiple events from the same CLI run can be stitched together. Detection is env-var based and never collects user content. Set GENMEDIA_USER_AGENT=<name> to override or self-attribute when running inside an agent we don't yet detect.

Opt out:

export GENMEDIA_NO_ANALYTICS=1            # per-shell
# or persist in config:
genmedia setup    # (toggle is currently file-only — set "analyticsOptOut": true)

Builds from source without a POSTHOG_KEY environment variable (the open-source default) report nothing — the analytics module no-ops at runtime.

genmedia init
genmedia init --force   # overwrite existing files

Installs the default genmedia skill bundle:

The bundle is installed into .agents/skills/ if the project has a .agents/ directory, otherwise into .claude/skills/. If neither directory exists, the command exits with a message asking you to create one and try again.

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

genmedia skills list                  # list everything in the registry
genmedia skills list image            # full-text search name + description
genmedia skills install genmedia
genmedia skills update
genmedia skills remove genmedia

Installs, updates, lists, and removes agent skills from the genmedia registry. skills list <query> runs full-text search via the hosted index API (GENMEDIA_SKILLS_API_URL, default https://genmedia.sh/skills); the no-query form fetches index.json directly from the registry.

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.

MIT