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
- Gemini CLI: YOLO mode, auto_edit and allowing specific shell commands
- Gemini CLI: turn off usage statistics and telemetry
- Configure Gemini CLI with settings.json
- Gemini CLI extensions and custom commands
- GEMINI.md in Gemini CLI: context file locations, imports and /memory
- Gemini CLI MCP servers: gemini mcp add and mcpServers in settings.json
- Gemini CLI headless mode: gemini -p, JSON output and exit codes for scripts and CI
- Gemini CLI sandbox: enable Docker, Podman, macOS Seatbelt or gVisor
- Gemini CLI hooks: settings.json, BeforeTool, AfterTool, exit codes and /hooks
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 →