gemini-cli

CLI Commands

Gemini CLI supports several built-in commands to help you manage your session, customize the interface, and control its behavior. These commands are prefixed with a forward slash (/), an at symbol (@), or an exclamation mark (!).

Slash commands (/)

Slash commands provide meta-level control over the CLI itself.

Built-in Commands

Custom Commands

For a quick start, see the example below.

Custom commands allow you to save and reuse your favorite or most frequently used prompts as personal shortcuts within Gemini CLI. You can create commands that are specific to a single project or commands that are available globally across all your projects, streamlining your workflow and ensuring consistency.

File Locations & Precedence

Gemini CLI discovers commands from two locations, loaded in a specific order:

  1. User Commands (Global): Located in ~/.gemini/commands/. These commands are available in any project you are working on.
  2. Project Commands (Local): Located in <your-project-root>/.gemini/commands/. These commands are specific to the current project and can be checked into version control to be shared with your team.

If a command in the project directory has the same name as a command in the user directory, the project command will always be used. This allows projects to override global commands with project-specific versions.

Naming and Namespacing

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

TOML File Format (v1)

Your command definition files must be written in the TOML format and use the .toml file extension.

Required Fields
Optional Fields

Handling Arguments

Custom commands support two powerful, low-friction methods for handling arguments. The CLI automatically chooses the correct method based on the content of your command’s prompt.

1. Shorthand Injection with ``

If your prompt contains the special placeholder ``, the CLI will replace that exact placeholder with all the text the user typed after the command name. This is perfect for simple, deterministic commands where you need to inject user input into a specific place in a larger prompt template.

Example (git/fix.toml):

# In: ~/.gemini/commands/git/fix.toml
# Invoked via: /git:fix "Button is misaligned on mobile"

description = "Generates a fix for a given GitHub issue."
prompt = "Please analyze the staged git changes and provide a code fix for the issue described here: ."

The model will receive the final prompt: Please analyze the staged git changes and provide a code fix for the issue described here: "Button is misaligned on mobile".

2. Default Argument Handling

If your prompt does not contain the special placeholder ``, the CLI uses a default behavior for handling arguments.

If you provide arguments to the command (e.g., /mycommand arg1), the CLI will append the full command you typed to the end of the prompt, separated by two newlines. This allows the model to see both the original instructions and the specific arguments you just provided.

If you do not provide any arguments (e.g., /mycommand), the prompt is sent to the model exactly as it is, with nothing appended.

Example (changelog.toml):

This example shows how to create a robust command by defining a role for the model, explaining where to find the user’s input, and specifying the expected format and behavior.

# In: <project>/.gemini/commands/changelog.toml
# Invoked via: /changelog 1.2.0 added "Support for default argument parsing."

description = "Adds a new entry to the project's CHANGELOG.md file."
prompt = """
# Task: Update Changelog

You are an expert maintainer of this software project. A user has invoked a command to add a new entry to the changelog.

**The user's raw command is appended below your instructions.**

Your task is to parse the `<version>`, `<change_type>`, and `<message>` from their input and use the `write_file` tool to correctly update the `CHANGELOG.md` file.

## Expected Format
The command follows this format: `/changelog <version> <type> <message>`
- `<type>` must be one of: "added", "changed", "fixed", "removed".

## Behavior
1. Read the `CHANGELOG.md` file.
2. Find the section for the specified `<version>`.
3. Add the `<message>` under the correct `<type>` heading.
4. If the version or type section doesn't exist, create it.
5. Adhere strictly to the "Keep a Changelog" format.
"""

When you run /changelog 1.2.0 added "New feature", the final text sent to the model will be the original prompt followed by two newlines and the command you typed.

3. Executing Shell Commands with !{...}

You can make your commands dynamic by executing shell commands directly within your prompt and injecting their output. This is ideal for gathering context from your local environment, like reading file content or checking the status of Git.

When a custom command attempts to execute a shell command, Gemini CLI will now prompt you for confirmation before proceeding. This is a security measure to ensure that only intended commands can be run.

How It Works:

  1. Inject Commands: Use the !{...} syntax in your prompt to specify where the command should be run and its output injected.
  2. Confirm Execution: When you run the command, a dialog will appear listing the shell commands the prompt wants to execute.
  3. Grant Permission: You can choose to:
    • Allow once: The command(s) will run this one time.
    • Allow always for this session: The command(s) will be added to a temporary allowlist for the current CLI session and will not require confirmation again.
    • No: Cancel the execution of the shell command(s).

The CLI still respects the global excludeTools and coreTools settings. A command will be blocked without a confirmation prompt if it is explicitly disallowed in your configuration.

Example (git/commit.toml):

This command gets the staged git diff and uses it to ask the model to write a commit message.

# In: <project>/.gemini/commands/git/commit.toml
# Invoked via: /git:commit

description = "Generates a Git commit message based on staged changes."

# The prompt uses !{...} to execute the command and inject its output.
prompt = """
Please generate a Conventional Commit message based on the following git diff:

```diff
!{git diff --staged}
```

"""

When you run /git:commit, the CLI first executes git diff --staged, then replaces !{git diff --staged} with the output of that command before sending the final, complete prompt to the model.

Example: A “Pure Function” Refactoring Command

Let’s create a global command that asks the model to refactor a piece of code.

1. Create the file and directories:

First, ensure the user commands directory exists, then create a refactor subdirectory for organization and the final TOML file.

mkdir -p ~/.gemini/commands/refactor
touch ~/.gemini/commands/refactor/pure.toml

2. Add the content to the file:

Open ~/.gemini/commands/refactor/pure.toml in your editor and add the following content. We are including the optional description for best practice.

# In: ~/.gemini/commands/refactor/pure.toml
# This command will be invoked via: /refactor:pure

description = "Asks the model to refactor the current context into a pure function."

prompt = """
Please analyze the code I've provided in the current context.
Refactor it into a pure function.

Your response should include:
1. The refactored, pure function code block.
2. A brief explanation of the key changes you made and why they contribute to purity.
"""

3. Run the Command:

That’s it! You can now run your command in the CLI. First, you might add a file to the context, and then invoke your command:

> @my-messy-function.js
> /refactor:pure

Gemini CLI will then execute the multi-line prompt defined in your TOML file.

At commands (@)

At commands are used to include the content of files or directories as part of your prompt to Gemini. These commands include git-aware filtering.

Error handling for @ commands

Shell mode & passthrough commands (!)

The ! prefix lets you interact with your system’s shell directly from within Gemini CLI.

This site is open source. Improve this page.