Skip to content
AgentAtlas

Gemini CLI custom slash commands: TOML files, {{args}}, !{shell} and @{file}

How do I create custom slash commands in Gemini CLI?

Create a .toml file with a prompt field in ~/.gemini/commands/ for global commands or .gemini/commands/ in your project. The file path becomes the command name, so git/commit.toml runs as /git:commit. Run /commands reload to pick up changes without restarting.

Compare: custom slash commands in every AI coding agent →

File locations and precedence

  • User (global): ~/.gemini/commands/
  • Project: <project-root>/.gemini/commands/ (can be checked into git)
  • If both define the same name, the project command wins.
  • Subfolders become namespaces: .gemini/commands/git/commit.toml is /git:commit.

Minimal command file

prompt is required. description is optional and shows in /help.

~/.gemini/commands/refactor/pure.toml

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.
"""

Create the folder (macOS/Linux)

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

Pass arguments with {{args}}

{{args}} is replaced with the text typed after the command. Inside a !{...} block it is shell escaped. If the prompt has no {{args}} and you pass arguments, the CLI appends your full command after two newlines.

.gemini/commands/git/fix.toml

description = "Generates a fix for a given issue."
prompt = "Please provide a code fix for the issue described here: {{args}}."

Inject shell output and files

  • !{command} runs a shell command and inserts its output. The CLI asks you to confirm first.
  • @{path} inserts a file's content or a directory listing, respecting .gitignore and .geminiignore.
  • @{...} is processed before !{...} and {{args}}.

.gemini/commands/git/commit.toml

description = "Generates a Git commit message based on staged changes."
prompt = """
Please generate a Conventional Commit message based on the following git diff:

!{git diff --staged}
"""

.gemini/commands/review.toml

description = "Reviews the provided context using a best practice guide."
prompt = """
You are an expert code reviewer.

Your task is to review {{args}}.

@{docs/best-practices.md}
"""

Reload and list commands

Inside Gemini CLI

/commands reload
/commands list

Sources

More Gemini CLI guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →