Custom commands in Gemini CLI

Official Link:https://geminicli.com/docs/cli/custom-commands/

Introduction

Custom commands in Gemini CLI let you save and reuse your favorite prompts as shortcut-style commands. Instead of typing the same long instruction again and again, you can store it in a .toml file and run it with a short slash command such as /review, /git:commit, or /refactor:pure.

This makes your workflow faster, more consistent, and easier to manage across projects.

What are Custom Commands?

A custom command is a reusable prompt stored in a TOML file. Gemini CLI reads these files and turns them into slash commands.

For example:

• A file named test.toml becomes /test
• A file named git/commit.toml becomes /git:commit
• A file named refactor/pure.toml becomes /refactor:pure

Custom commands are useful when you:

• repeat the same prompts often
• want consistent results from Gemini
• want project-specific prompts for a team
• want global shortcuts available in every project

Why Custom Commands are Useful

Custom commands help you:

• save time by reusing prompts
• standardize workflows
• avoid typing long repetitive instructions
• create team-shared command libraries
• combine prompts with file content, shell output, and user arguments

In simple words, custom commands turn Gemini CLI into a more personalized and automated tool.

File Locations and Precedence

Gemini CLI loads commands from two main locations.

1. User commands (global): These commands are available in every project.
   • Location:~/.gemini/commands/
2. Project commands (local): These commands are available only inside the current project.
   • Location:<your-project-root>/.gemini/commands/

Precedence Rule

If a project command and a user command have the same name, the project command wins. That means local project commands can override your global commands.

Example:

If both of these exist:

• ~/.gemini/commands/review.toml
• <project>/.gemini/commands/review.toml

Then Gemini CLI will use the project version when you are inside that project.

Naming and Namespacing

Command names come from the file path relative to the commands directory.

Examples:

• ~/.gemini/commands/test.toml → /test
• <project>/.gemini/commands/git/commit.toml → /git:commit
• <project>/.gemini/commands/refactor/pure.toml → /refactor:pure

Key idea

• file name becomes command name
• subfolders become namespaces
• / or \ in the path becomes : in the command

This helps keep commands organized.

Reloading Commands

After creating or editing a command file, run:

Bash

/commands reload    

This refreshes the available commands without restarting Gemini CLI.

TOML File Format (v1)

Custom commands must be written in:

• TOML format
• use the .toml extension

Each command file usually contains:

• prompt (string): It is a required field. This is the instruction sent to the Gemini model when the command runs. It can be:
• single-line
• multi-line
• description (string): It is an optional field. This is a one-line explanation of what the command does. It appears in /help menus and makes the command easier to understand.If you do not provide it, Gemini CLI may generate a generic description based on the filename.

Running Your Custom Command in Gemini CLI

After creating or modifying a command file, you must restart your Gemini CLI session for the changes to take effect.

1. Type /quit to exit.
2. Run gemini to start a new session.
3. Type / and you should see your custom command in the list.

Basic Example

Suppose you create a summarize.toml file with the following content:

summarize.toml file

description = "Asks the model to summarize the given file."
prompt = "Please summarize the given file {{args}} in simple terms."

If this file is saved as:

Folder Structure

📁 ~/.gemini/
└── 📁 commands/
    └── 📄 summarize.toml

You can run it as:

Bash

/summarize

Using Arguments with {{args}}

The {{args}} placeholder is used to capture any text the user types after the command.

For example, if you run:

Bash

/summarize filename.txt

The text filename.txt will be injected into the prompt where {{args}} is placed.