genmedia CLI: fal.ai endpoint runner

genmedia is the agent-first CLI for fal.ai. It works in a terminal for humans (pretty output) and equally well for agents (structured JSON when piped or with --json). All other skills in this repo call genmedia for execution, they do not wrap the fal.ai HTTP API directly.

For the full command surface (every flag, every option, every example), see references/full-reference.md.

Critical rules

1. Always use --json when an agent will read the output. Pretty mode is for humans only.
2. Prefer smart routing for default-quality requests. genmedia run "<prompt>" (no endpoint, no --prompt needed) classifies the prompt and routes to a sensible default per modality. Only do explicit endpoint discovery when the user names a model, asks for a non-default behavior (specific style, quality tier, parameter), or the smart-route default is wrong for the task.
3. Never invent endpoint IDs. When you do need a specific endpoint, use genmedia models "<query>" to discover (auto-filters by inferred modality) and genmedia models --endpoint_id <id> to verify.
4. Inspect schema before running with custom params. genmedia schema <endpoint_id> --json shows the exact field names. Smart routing only needs prompt; explicit endpoints with custom params need a schema check first or guessed flags fail with 422.
5. Save files with --download, not curl. The CLI handles authentication, naming, and file format detection.
6. Use --async for long-running generation. Image work usually completes inline; video/audio/3D usually need queue + status polling.

Command index