Skip to content
Universal Modder Guides

install / gemini-cli

How to install the Universal Modder Gemini CLI extension

Quick answer

Install the universal-modder extension in Gemini CLI with a single command, configure optional asset credentials, and launch the modding workflow in about five minutes. The extension is free; Gemini CLI usage depends on your Google account or API quota, and fal asset generation is a separate paid service.

Prerequisites

  • A single-player PC game you legally own, within the usage boundary below.
  • Gemini CLI installed and configured on your machine.
  • Python 3.10+ and ffmpeg installed; uv is recommended.
  • A separate mod working folder on your system.
  • A fal account and API key if you want generated sprites, 3D models, or audio.
  • Blender if you need to render 3D models into game-ready sprites.

Steps: how to install Universal Modder in Gemini CLI

  1. Check environment prerequisites

    What to do

    Open a terminal in your mod working folder. Verify that Python, uv, and ffmpeg are installed and accessible on PATH.

    Command

    Command
    python --version
    uv --version
    ffmpeg -version

    What you should see

    Each command outputs its installed version number.

    If something goes wrong

    If tools are missing on Windows, install them using winget and open a new terminal:

    Command
    winget install Python.Python.3.12
    winget install astral-sh.uv
    winget install Gyan.FFmpeg
  2. Install the extension in Gemini CLI

    What to do

    Run the extension install command pointing directly to the universal-modder repository URL.

    Command

    Command
    gemini extensions install https://github.com/rehan-remade/universal-modder

    What you should see

    Gemini CLI registers the universal-modder extension defined in gemini-extension.json.

    If something goes wrong

    If the install command fails, check your network connectivity and ensure Git is installed and available in your environment.

  3. Configure the fal API key for assets

    What to do

    If you want the agent to generate sprites, textures, 3D models, or audio, set your fal API key in your environment. gemini-extension.json configures the fal MCP server at https://mcp.fal.ai/mcp using Bearer ${FAL_KEY} and registers FAL_KEY as an extension setting.

    Command

    Windows terminal:

    Command
    setx FAL_KEY your_key

    macOS or Linux terminal:

    Command
    export FAL_KEY=...

    What you should see

    fal displays your API key once upon creation, so save it securely.

    If something goes wrong

    On Windows, restart your terminal after running setx so Gemini CLI inherits the variable. You can use the extension without a fal key; asset generation will be skipped.

  4. Launch Gemini CLI in your mod folder

    What to do

    Open a terminal in your mod working folder and start Gemini CLI.

    Command

    Command
    gemini

    What you should see

    Gemini CLI starts and loads AGENTS.md as its context file and links skills via .gemini/skills.

    If something goes wrong

    If the extension is not loaded, verify that gemini-extension.json is recognized in your Gemini CLI configuration.

  5. Launch the modding workflow in Gemini CLI

    What to do

    Launch Gemini CLI in your mod folder. Gemini CLI automatically loads AGENTS.md as its context file (contextFileName: "AGENTS.md"). Describe your mod in natural language:

    Command

    Command
    Mod this game: add a new weapon with fal-generated sprites

    What you should see

    The agent starts with skills/mod-any-game/SKILL.md, searches the knowledge base, runs recon to choose a route, creates MODLOG.md in the working folder, and backs up saves before any modded launch.

    If something goes wrong

    The agent asks before driving mouse and keyboard input, installing loaders into game folders, changing the registry, or publishing. It explicitly refuses to bypass anti-cheat, DRM, or game ownership checks.

Verify it worked

  • Confirm that python --version, uv --version, and ffmpeg -version return valid version outputs.
  • Verify that Gemini CLI lists the universal-modder extension.
  • Check that gemini-extension.json connects to https://mcp.fal.ai/mcp when FAL_KEY is set.
  • Launch Gemini CLI, describe your mod, and verify that MODLOG.md is created in your mod directory.
  • Test the resulting mod directly inside the real game client yourself.

FAQ

How do I install the Universal Modder Gemini CLI extension?

Run gemini extensions install https://github.com/rehan-remade/universal-modder, in your terminal.

Can I use the Gemini CLI extension without a fal API key?

Yes. The extension handles game engine reconnaissance, reverse engineering, save backups, and code editing without fal. An API key is only needed if you want the fal MCP server or um fal to generate 2D/3D assets or audio.

Do I need a paid account to use Gemini CLI with Universal Modder?

The universal-modder extension is free open-source software under the MIT license. Using Gemini CLI depends on your Google account or API quota, while fal asset generation is a separate paid service.

What should I do if Gemini CLI reports an extension load error?

Check that your internet connection allows access to GitHub releases, and reinstall the extension by re-running gemini extensions install https://github.com/rehan-remade/universal-modder. Restart your shell to refresh extension paths.

How do I verify that Gemini CLI has access to game files?

Launch Gemini CLI directly from your game or mod project folder. Gemini CLI operates in its execution working directory, so starting it from your mod workspace ensures prompt context and file inspection tools target the right files.