Plugin developer guide

Publish a Gemini CLI extension to the extension gallery

By HOL · Reviewed by Michael Kantor on

Direct answer

The gallery lists public GitHub repositories tagged with the gemini-cli-extension topic whose gemini-extension.json sits at the repository root or the root of the release archive. Generate the manifest with hol-guard plugin package --runtimes gemini-cli, validate it with gemini extensions validate, move it to the root and add the topic. Tagged repositories are crawled daily, and users install with gemini extensions install and the repository URL.

Who this is for

MCP server and plugin authors who want Gemini CLI users to find their extension in the gallery.

Good fit

  • An MCP server already packaged for Claude Code or Codex
  • A context file and MCP servers shipped as one extension
  • Versioned releases through GitHub Releases

Not a fit

  • Skills, commands, agents and hooks, which a Gemini CLI extension package does not carry

Steps

  1. 1.Install HOL Guard

    The Plugin Kit ships inside HOL Guard. It needs Python 3.10 or newer and pipx. If Guard is already installed, upgrade it so the Kit commands below are available.

    pipx install hol-guard
pipx upgrade hol-guard
hol-guard --version

  2. 2.Check the plugin

    The check detects every manifest in the folder, lists skills and MCP servers, and reports what each runtime would reject. It exits 0 when the plugin passes, 1 when it has errors and 2 when it could not run. It reads only the folder, runs no commands and makes no network calls.

    hol-guard plugin check .

  3. 3.Write the extension manifest

    Packaging writes gemini-extension.json with your MCP servers and context file into its own folder under the output directory.

    hol-guard plugin package . --runtimes gemini-cli --out dist/hol-plugin
gemini extensions validate dist/hol-plugin/gemini-cli

  4. 4.Put the manifest at the root

    The gallery reads gemini-extension.json from the absolute root of the repository or of the release archive. Commit it at the root, or attach an archive that has it at its root to a GitHub release.

  5. 5.Tag the repository

    Make the repository public and add the gemini-cli-extension topic in its About section. The gallery crawls tagged repositories daily.

  6. 6.Install it the way users will

    Users install from the repository URL and can pin a branch, tag or commit with --ref. With GitHub Releases, Gemini CLI updates to the release marked Latest.

    gemini extensions install https://github.com/owner/repo
gemini extensions list

  7. 7.Add the install block to your README

    hol-guard plugin links --block prints a README block between hol-install-block markers: one hol-guard plugin install command, how to get HOL Guard, and each runtime's own install commands for the runtimes the repository already supports. Paste it into the README; HOL finds it on its next scan and shows the install count on your listing once enough installs are reported.

    hol-guard plugin links . --block

  8. 8.Connect the repository on HOL

    Open the connect page with your repository to verify ownership and claim the listing. hol-guard plugin links prints the same link with the repository filled in.

    hol-guard plugin links .

Limitations

  • The gallery is populated by a crawler, so a new extension can take a day to appear.
  • Gemini CLI extensions do not carry skills, commands, agents or hooks from other runtimes.
  • A listing, a passing check or a marketplace review is not a safety guarantee. HOL shows its scan evidence on the listing so users can judge for themselves.

Questions

Do I need GitHub Releases?

No. Users can install from the git repository and are prompted to update when you push to the branch they installed. Releases make installs faster and let you ship platform archives.

How are release archives named?

Platform archives use {platform}.{arch}.{name}.{extension}, with darwin, linux or win32 and x64 or arm64.

Sources

Related guides

List it on HOL

Connect the repository to verify ownership and claim the listing. New plugins can be submitted for free.

Connect your plugin repository