Developers & Practitioners

Gemini CLI: Custom slash commands

July 30, 2025

https://storage.googleapis.com/gweb-cloudblog-publish/images/custom_slash_commands_header.max-2600x2600.png

Jack Wotherspoon

Developer Advocate

Abhi Patel

Software Engineer

Today, we're announcing support for custom slash commands in Gemini CLI! This highly requested feature lets you define reusable prompts for streamlining interactions with Gemini CLI and helps improve efficiency across workflows. Slash commands can be defined in local .toml files or through Model Context Protocol (MCP) prompts. Get ready to transform how you leverage Gemini CLI with the new power of slash commands!

https://storage.googleapis.com/gweb-cloudblog-publish/original_images/custom_slash_commands_review.gif

To use slash commands, make sure that you update to the latest version of Gemini CLI.

Update npx:

Update npm:

Powerful and extensible foundation with .toml files

The foundation of custom slash commands is rooted in .toml files.

The .toml file provides a powerful and structured base on which to build extensive support for complex commands. To help support a wide range of users, we made the required keys minimal (just prompt). And we support easy-to-use args with {{args}} and shell command execution !{...} directly into the prompt.

Here is an example .toml file that is invoked using /review <issue_number> from Gemini CLI to review a GitHub PR. Notice that the file name defines the command name and it's case sensitive. For more information about custom slash commands, see the Custom Commands section of the Gemini CLI documentation.

Namespacing

The name of a command is determined by its file path relative to the commands directory. Sub-directories are used to create namespaced commands, with the path separator (/ or \) being converted to a colon (:).

A file at <project>/.gemini/commands/test.toml becomes the command /test.
A file at <project>/.gemini/commands/git/commit.toml becomes the namespaced command /git:commit.

https://storage.googleapis.com/gweb-cloudblog-publish/original_images/custom_slash_commands_namespaces.gif

This allows grouping related commands under a single namespace.

Building a slash command

The next few sections show you how to build a slash command for Gemini CLI.

1 - Create the command file

First, create a file named plan.toml inside the ~/.gemini/commands/ directory. Doing so will let you create a /plan command to tell Gemini CLI to only plan the changes by providing a step-by-step plan and to not start on implementation. This approach will let you provide feedback and iterate on the plan before implementation.

Custom slash commands can be scoped to an individual user or project by defining the .toml files in designated directories.

User-scoped commands are available across all Gemini CLI projects for a user and are stored in ~/.gemini/commands/ (note the ~).
Project-scoped commands are only available from sessions within a given project and are stored in .gemini/commands/.

Hint: To streamline project workflows, check these into Git repositories!

2 - Add the command definition

Open plan.toml and add the following content:

# ~/.gemini/commands/plan.toml

description="Investigates and creates a strategic plan to accomplish a task."
prompt = """
Your primary role is that of a strategist, not an implementer.
Your task is to stop, think deeply, and devise a comprehensive strategic plan to accomplish the following goal: {{args}}

You MUST NOT write, modify, or execute any code. Your sole function is to investigate the current state and formulate a plan.

Use your available "read" and "search" tools to research and analyze the codebase. Gather all necessary context before presenting your strategy.

Present your strategic plan in markdown. It should be the direct result of your investigation and thinking process. Structure your response with the following sections:

1.  **Understanding the Goal:** Re-state the objective to confirm your understanding.
2.  **Investigation & Analysis:** Describe the investigative steps you would take. What files would you need to read? What would you search for? What critical questions need to be answered before any work begins?
3.  **Proposed Strategic Approach:** Outline the high-level strategy. Break the approach down into logical phases and describe the work that should happen in each.
4.  **Verification Strategy:** Explain how the success of this plan would be measured. What should be tested to ensure the goal is met without introducing regressions?
5.  **Anticipated Challenges & Considerations:** Based on your analysis, what potential risks, dependencies, or trade-offs do you foresee?

Your final output should be ONLY this strategic plan.
"""

3 - Use the command

Now you can use this command within Gemini CLI:

Gemini will plan out the changes and output a detailed step-by-step execution plan!

Enriched integration with MCP Prompts

Gemini CLI now offers a more integrated experience with MCP by supporting MCP Prompts as slash commands! MCP provides a standardized way for servers to expose prompt templates to clients. Gemini CLI utilizes this to expose available prompts for configured MCP servers and make the prompts available as slash commands.

The name and description of the MCP prompt is used as the slash command name and description. MCP prompt arguments are also supported and leveraged in slash commands by using /mycommand --<argument_name>="<argument_value>" or positionally /mycommand <argument1> <argument2>.

The following is an example /research command that uses FastMCP Python server:

https://storage.googleapis.com/gweb-cloudblog-publish/original_images/custom_slash_commands_mcp.gif

Easy to get started

So what are you waiting for? Upgrade your terminal experience with Gemini CLI today and try out custom slash commands to streamline your workflows. To learn more, check out the Custom Commands documentation for the Gemini CLI.

Posted in