@didim365/agent-cli-core 0.1.0

package/dist/docs/cli/commands.md

@@ -0,0 +1,375 @@
+# 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
+
+- **`/bug`**
+  - **Description:** File an issue about Gemini CLI. By default, the issue is
+    filed within the GitHub repository for Gemini CLI. The string you enter
+    after `/bug` will become the headline for the bug being filed. The default
+    `/bug` behavior can be modified using the `advanced.bugCommand` setting in
+    your `.gemini/settings.json` files.
+
+- **`/chat`**
+  - **Description:** Save and resume conversation history for branching
+    conversation state interactively, or resuming a previous state from a later
+    session.
+  - **Sub-commands:**
+    - **`save`**
+      - **Description:** Saves the current conversation history. You must add a
+        `<tag>` for identifying the conversation state.
+      - **Usage:** `/chat save <tag>`
+      - **Details on checkpoint location:** The default locations for saved chat
+        checkpoints are:
+        - Linux/macOS: `~/.gemini/tmp/<project_hash>/`
+        - Windows: `C:\Users\<YourUsername>\.gemini\tmp\<project_hash>\`
+        - **Behavior:** Chats are saved into a project-specific directory,
+          determined by where you run the CLI. Consequently, saved chats are
+          only accessible when working within that same project.
+        - **Note:** These checkpoints are for manually saving and resuming
+          conversation states. For automatic checkpoints created before file
+          modifications, see the
+          [Checkpointing documentation](../cli/checkpointing.md).
+    - **`resume`**
+      - **Description:** Resumes a conversation from a previous save.
+      - **Usage:** `/chat resume <tag>`
+      - **Note:** You can only resume chats that were saved within the current
+        project. To resume a chat from a different project, you must run the
+        Gemini CLI from that project's directory.
+    - **`list`**
+      - **Description:** Lists available tags for chat state resumption.
+      - **Note:** This command only lists chats saved within the current
+        project. Because chat history is project-scoped, chats saved in other
+        project directories will not be displayed.
+    - **`delete`**
+      - **Description:** Deletes a saved conversation checkpoint.
+      - **Usage:** `/chat delete <tag>`
+    - **`share`**
+      - **Description** Writes the current conversation to a provided Markdown
+        or JSON file.
+      - **Usage** `/chat share file.md` or `/chat share file.json`. If no
+        filename is provided, then the CLI will generate one.
+
+- **`/clear`**
+  - **Description:** Clear the terminal screen, including the visible session
+    history and scrollback within the CLI. The underlying session data (for
+    history recall) might be preserved depending on the exact implementation,
+    but the visual display is cleared.
+  - **Keyboard shortcut:** Press **Ctrl+L** at any time to perform a clear
+    action.
+
+- **`/compress`**
+  - **Description:** Replace the entire chat context with a summary. This saves
+    on tokens used for future tasks while retaining a high level summary of what
+    has happened.
+
+- **`/copy`**
+  - **Description:** Copies the last output produced by Gemini CLI to your
+    clipboard, for easy sharing or reuse.
+  - **Behavior:**
+    - Local sessions use system clipboard tools (pbcopy/xclip/clip).
+    - Remote sessions (SSH/WSL) use OSC 52 and require terminal support.
+  - **Note:** This command requires platform-specific clipboard tools to be
+    installed.
+    - On Linux, it requires `xclip` or `xsel`. You can typically install them
+      using your system's package manager.
+    - On macOS, it requires `pbcopy`, and on Windows, it requires `clip`. These
+      tools are typically pre-installed on their respective systems.
+
+- **`/directory`** (or **`/dir`**)
+  - **Description:** Manage workspace directories for multi-directory support.
+  - **Sub-commands:**
+    - **`add`**:
+      - **Description:** Add a directory to the workspace. The path can be
+        absolute or relative to the current working directory. Moreover, the
+        reference from home directory is supported as well.
+      - **Usage:** `/directory add <path1>,<path2>`
+      - **Note:** Disabled in restrictive sandbox profiles. If you're using
+        that, use `--include-directories` when starting the session instead.
+    - **`show`**:
+      - **Description:** Display all directories added by `/directory add` and
+        `--include-directories`.
+      - **Usage:** `/directory show`
+
+- **`/editor`**
+  - **Description:** Open a dialog for selecting supported editors.
+
+- **`/extensions`**
+  - **Description:** Lists all active extensions in the current Gemini CLI
+    session. See [Gemini CLI Extensions](../extensions/index.md).
+
+- **`/help`** (or **`/?`**)
+  - **Description:** Display help information about Gemini CLI, including
+    available commands and their usage.
+
+- **`/mcp`**
+  - **Description:** Manage configured Model Context Protocol (MCP) servers.
+  - **Sub-commands:**
+    - **`list`** or **`ls`**:
+      - **Description:** List configured MCP servers and tools. This is the
+        default action if no subcommand is specified.
+    - **`desc`**
+      - **Description:** List configured MCP servers and tools with
+        descriptions.
+    - **`schema`**:
+      - **Description:** List configured MCP servers and tools with descriptions
+        and schemas.
+    - **`auth`**:
+      - **Description:** Authenticate with an OAuth-enabled MCP server.
+      - **Usage:** `/mcp auth <server-name>`
+      - **Details:** If `<server-name>` is provided, it initiates the OAuth flow
+        for that server. If no server name is provided, it lists all configured
+        servers that support OAuth authentication.
+    - **`refresh`**:
+      - **Description:** Restarts all MCP servers and re-discovers their
+        available tools.
+
+- [**`/model`**](./model.md)
+  - **Description:** Opens a dialog to choose your Gemini model.
+
+- **`/memory`**
+  - **Description:** Manage the AI's instructional context (hierarchical memory
+    loaded from `GEMINI.md` files).
+  - **Sub-commands:**
+    - **`add`**:
+      - **Description:** Adds the following text to the AI's memory. Usage:
+        `/memory add <text to remember>`
+    - **`show`**:
+      - **Description:** Display the full, concatenated content of the current
+        hierarchical memory that has been loaded from all `GEMINI.md` files.
+        This lets you inspect the instructional context being provided to the
+        Gemini model.
+    - **`refresh`**:
+      - **Description:** Reload the hierarchical instructional memory from all
+        `GEMINI.md` files found in the configured locations (global,
+        project/ancestors, and sub-directories). This command updates the model
+        with the latest `GEMINI.md` content.
+    - **`list`**:
+      - **Description:** Lists the paths of the GEMINI.md files in use for
+        hierarchical memory.
+    - **Note:** For more details on how `GEMINI.md` files contribute to
+      hierarchical memory, see the
+      [CLI Configuration documentation](../get-started/configuration.md).
+
+- **`/restore`**
+  - **Description:** Restores the project files to the state they were in just
+    before a tool was executed. This is particularly useful for undoing file
+    edits made by a tool. If run without a tool call ID, it will list available
+    checkpoints to restore from.
+  - **Usage:** `/restore [tool_call_id]`
+  - **Note:** Only available if checkpointing is configured via
+    [settings](../get-started/configuration.md). See
+    [Checkpointing documentation](../cli/checkpointing.md) for more details.
+
+- **`/resume`**
+  - **Description:** Browse and resume previous conversation sessions. Opens an
+    interactive session browser where you can search, filter, and select from
+    automatically saved conversations.
+  - **Features:**
+    - **Session Browser:** Interactive interface showing all saved sessions with
+      timestamps, message counts, and first user message for context
+    - **Search:** Use `/` to search through conversation content across all
+      sessions
+    - **Sorting:** Sort sessions by date or message count
+    - **Management:** Delete unwanted sessions directly from the browser
+    - **Resume:** Select any session to resume and continue the conversation
+  - **Note:** All conversations are automatically saved as you chat - no manual
+    saving required. See [Session Management](../cli/session-management.md) for
+    complete details.
+
+- [**`/settings`**](./settings.md)
+  - **Description:** Open the settings editor to view and modify Gemini CLI
+    settings.
+  - **Details:** This command provides a user-friendly interface for changing
+    settings that control the behavior and appearance of Gemini CLI. It is
+    equivalent to manually editing the `.gemini/settings.json` file, but with
+    validation and guidance to prevent errors. See the
+    [settings documentation](./settings.md) for a full list of available
+    settings.
+  - **Usage:** Simply run `/settings` and the editor will open. You can then
+    browse or search for specific settings, view their current values, and
+    modify them as desired. Changes to some settings are applied immediately,
+    while others require a restart.
+
+- [**`/skills`**](./skills.md)
+  - **Description:** (Experimental) Manage Agent Skills, which provide on-demand
+    expertise and specialized workflows.
+  - **Sub-commands:**
+    - **`list`**:
+      - **Description:** List all discovered skills and their current status
+        (enabled/disabled).
+    - **`enable`**:
+      - **Description:** Enable a specific skill by name.
+      - **Usage:** `/skills enable <name>`
+    - **`disable`**:
+      - **Description:** Disable a specific skill by name.
+      - **Usage:** `/skills disable <name>`
+    - **`reload`**:
+      - **Description:** Refresh the list of discovered skills from all tiers
+        (workspace, user, and extensions).
+
+- **`/stats`**
+  - **Description:** Display detailed statistics for the current Gemini CLI
+    session, including token usage, cached token savings (when available), and
+    session duration. Note: Cached token information is only displayed when
+    cached tokens are being used, which occurs with API key authentication but
+    not with OAuth authentication at this time.
+
+- [**`/theme`**](./themes.md)
+  - **Description:** Open a dialog that lets you change the visual theme of
+    Gemini CLI.
+
+- **`/auth`**
+  - **Description:** Open a dialog that lets you change the authentication
+    method.
+
+- **`/about`**
+  - **Description:** Show version info. Please share this information when
+    filing issues.
+
+- [**`/tools`**](../tools/index.md)
+  - **Description:** Display a list of tools that are currently available within
+    Gemini CLI.
+  - **Usage:** `/tools [desc]`
+  - **Sub-commands:**
+    - **`desc`** or **`descriptions`**:
+      - **Description:** Show detailed descriptions of each tool, including each
+        tool's name with its full description as provided to the model.
+    - **`nodesc`** or **`nodescriptions`**:
+      - **Description:** Hide tool descriptions, showing only the tool names.
+
+- **`/privacy`**
+  - **Description:** Display the Privacy Notice and allow users to select
+    whether they consent to the collection of their data for service improvement
+    purposes.
+
+- **`/quit`** (or **`/exit`**)
+  - **Description:** Exit Gemini CLI.
+
+- **`/vim`**
+  - **Description:** Toggle vim mode on or off. When vim mode is enabled, the
+    input area supports vim-style navigation and editing commands in both NORMAL
+    and INSERT modes.
+  - **Features:**
+    - **NORMAL mode:** Navigate with `h`, `j`, `k`, `l`; jump by words with `w`,
+      `b`, `e`; go to line start/end with `0`, `$`, `^`; go to specific lines
+      with `G` (or `gg` for first line)
+    - **INSERT mode:** Standard text input with escape to return to NORMAL mode
+    - **Editing commands:** Delete with `x`, change with `c`, insert with `i`,
+      `a`, `o`, `O`; complex operations like `dd`, `cc`, `dw`, `cw`
+    - **Count support:** Prefix commands with numbers (e.g., `3h`, `5w`, `10G`)
+    - **Repeat last command:** Use `.` to repeat the last editing operation
+    - **Persistent setting:** Vim mode preference is saved to
+      `~/.gemini/settings.json` and restored between sessions
+  - **Status indicator:** When enabled, shows `[NORMAL]` or `[INSERT]` in the
+    footer
+
+- **`/init`**
+  - **Description:** To help users easily create a `GEMINI.md` file, this
+    command analyzes the current directory and generates a tailored context
+    file, making it simpler for them to provide project-specific instructions to
+    the Gemini agent.
+
+### Custom commands
+
+Custom commands allow you to create personalized shortcuts for your most-used
+prompts. For detailed instructions on how to create, manage, and use them,
+please see the dedicated [Custom Commands documentation](./custom-commands.md).
+
+## Input prompt shortcuts
+
+These shortcuts apply directly to the input prompt for text manipulation.
+
+- **Undo:**
+  - **Keyboard shortcut:** Press **Ctrl+z** to undo the last action in the input
+    prompt.
+
+- **Redo:**
+  - **Keyboard shortcut:** Press **Ctrl+Shift+Z** to redo the last undone action
+    in the input prompt.
+
+## 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.
+
+- **`@<path_to_file_or_directory>`**
+  - **Description:** Inject the content of the specified file or files into your
+    current prompt. This is useful for asking questions about specific code,
+    text, or collections of files.
+  - **Examples:**
+    - `@path/to/your/file.txt Explain this text.`
+    - `@src/my_project/ Summarize the code in this directory.`
+    - `What is this file about? @README.md`
+  - **Details:**
+    - If a path to a single file is provided, the content of that file is read.
+    - If a path to a directory is provided, the command attempts to read the
+      content of files within that directory and any subdirectories.
+    - Spaces in paths should be escaped with a backslash (e.g.,
+      `@My\ Documents/file.txt`).
+    - The command uses the `read_many_files` tool internally. The content is
+      fetched and then inserted into your query before being sent to the Gemini
+      model.
+    - **Git-aware filtering:** By default, git-ignored files (like
+      `node_modules/`, `dist/`, `.env`, `.git/`) are excluded. This behavior can
+      be changed via the `context.fileFiltering` settings.
+    - **File types:** The command is intended for text-based files. While it
+      might attempt to read any file, binary files or very large files might be
+      skipped or truncated by the underlying `read_many_files` tool to ensure
+      performance and relevance. The tool indicates if files were skipped.
+  - **Output:** The CLI will show a tool call message indicating that
+    `read_many_files` was used, along with a message detailing the status and
+    the path(s) that were processed.
+
+- **`@` (Lone at symbol)**
+  - **Description:** If you type a lone `@` symbol without a path, the query is
+    passed as-is to the Gemini model. This might be useful if you are
+    specifically talking _about_ the `@` symbol in your prompt.
+
+### Error handling for `@` commands
+
+- If the path specified after `@` is not found or is invalid, an error message
+  will be displayed, and the query might not be sent to the Gemini model, or it
+  will be sent without the file content.
+- If the `read_many_files` tool encounters an error (e.g., permission issues),
+  this will also be reported.
+
+## Shell mode and passthrough commands (`!`)
+
+The `!` prefix lets you interact with your system's shell directly from within
+Gemini CLI.
+
+- **`!<shell_command>`**
+  - **Description:** Execute the given `<shell_command>` using `bash` on
+    Linux/macOS or `powershell.exe -NoProfile -Command` on Windows (unless you
+    override `ComSpec`). Any output or errors from the command are displayed in
+    the terminal.
+  - **Examples:**
+    - `!ls -la` (executes `ls -la` and returns to Gemini CLI)
+    - `!git status` (executes `git status` and returns to Gemini CLI)
+
+- **`!` (Toggle shell mode)**
+  - **Description:** Typing `!` on its own toggles shell mode.
+    - **Entering shell mode:**
+      - When active, shell mode uses a different coloring and a "Shell Mode
+        Indicator".
+      - While in shell mode, text you type is interpreted directly as a shell
+        command.
+    - **Exiting shell mode:**
+      - When exited, the UI reverts to its standard appearance and normal Gemini
+        CLI behavior resumes.
+
+- **Caution for all `!` usage:** Commands you execute in shell mode have the
+  same permissions and impact as if you ran them directly in your terminal.
+
+- **Environment variable:** When a command is executed via `!` or in shell mode,
+  the `GEMINI_CLI=1` environment variable is set in the subprocess's
+  environment. This allows scripts or tools to detect if they are being run from
+  within the Gemini CLI.

package/dist/docs/cli/custom-commands.md

@@ -0,0 +1,315 @@
+# Custom commands
+
+Custom commands let you 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 and 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 (`:`).
+
+- A file at `~/.gemini/commands/test.toml` becomes the command `/test`.
+- A file at `<project>/.gemini/commands/git/commit.toml` becomes the namespaced
+  command `/git:commit`.
+
+## TOML file format (v1)
+
+Your command definition files must be written in the TOML format and use the
+`.toml` file extension.
+
+### Required fields
+
+- `prompt` (String): The prompt that will be sent to the Gemini model when the
+  command is executed. This can be a single-line or multi-line string.
+
+### Optional fields
+
+- `description` (String): A brief, one-line description of what the command
+  does. This text will be displayed next to your command in the `/help` menu.
+  **If you omit this field, a generic description will be generated from the
+  filename.**
+
+## Handling arguments
+
+Custom commands support two powerful methods for handling arguments. The CLI
+automatically chooses the correct method based on the content of your command's
+`prompt`.
+
+### 1. Context-aware injection with `{{args}}`
+
+If your `prompt` contains the special placeholder `{{args}}`, the CLI will
+replace that placeholder with the text the user typed after the command name.
+
+The behavior of this injection depends on where it is used:
+
+**A. Raw injection (outside shell commands)**
+
+When used in the main body of the prompt, the arguments are injected exactly as
+the user typed them.
+
+**Example (`git/fix.toml`):**
+
+```toml
+# Invoked via: /git:fix "Button is misaligned"
+
+description = "Generates a fix for a given issue."
+prompt = "Please provide a code fix for the issue described here: {{args}}."
+```
+
+The model receives:
+`Please provide a code fix for the issue described here: "Button is misaligned".`
+
+**B. Using arguments in shell commands (inside `!{...}` blocks)**
+
+When you use `{{args}}` inside a shell injection block (`!{...}`), the arguments
+are automatically **shell-escaped** before replacement. This allows you to
+safely pass arguments to shell commands, ensuring the resulting command is
+syntactically correct and secure while preventing command injection
+vulnerabilities.
+
+**Example (`/grep-code.toml`):**
+
+```toml
+prompt = """
+Please summarize the findings for the pattern `{{args}}`.
+
+Search Results:
+!{grep -r {{args}} .}
+"""
+```
+
+When you run `/grep-code It's complicated`:
+
+1. The CLI sees `{{args}}` used both outside and inside `!{...}`.
+2. Outside: The first `{{args}}` is replaced raw with `It's complicated`.
+3. Inside: The second `{{args}}` is replaced with the escaped version (e.g., on
+   Linux: `"It\'s complicated"`).
+4. The command executed is `grep -r "It's complicated" .`.
+5. The CLI prompts you to confirm this exact, secure command before execution.
+6. The final prompt is sent.
+
+### 2. Default argument handling
+
+If your `prompt` does **not** contain the special placeholder `{{args}}`, 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.
+
+```toml
+# 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.
+2.  **Argument substitution:** If `{{args}}` is present inside the block, it is
+    automatically shell-escaped (see
+    [Context-Aware Injection](#1-context-aware-injection-with-args) above).
+3.  **Robust parsing:** The parser correctly handles complex shell commands that
+    include nested braces, such as JSON payloads. **Note:** The content inside
+    `!{...}` must have balanced braces (`{` and `}`). If you need to execute a
+    command containing unbalanced braces, consider wrapping it in an external
+    script file and calling the script within the `!{...}` block.
+4.  **Security check and confirmation:** The CLI performs a security check on
+    the final, resolved command (after arguments are escaped and substituted). A
+    dialog will appear showing the exact command(s) to be executed.
+5.  **Execution and error reporting:** The command is executed. If the command
+    fails, the output injected into the prompt will include the error messages
+    (stderr) followed by a status line, e.g.,
+    `[Shell command exited with code 1]`. This helps the model understand the
+    context of the failure.
+
+**Example (`git/commit.toml`):**
+
+This command gets the staged git diff and uses it to ask the model to write a
+commit message.
+
+````toml
+# 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.
+
+### 4. Injecting file content with `@{...}`
+
+You can directly embed the content of a file or a directory listing into your
+prompt using the `@{...}` syntax. This is useful for creating commands that
+operate on specific files.
+
+**How it works:**
+
+- **File injection**: `@{path/to/file.txt}` is replaced by the content of
+  `file.txt`.
+- **Multimodal support**: If the path points to a supported image (e.g., PNG,
+  JPEG), PDF, audio, or video file, it will be correctly encoded and injected as
+  multimodal input. Other binary files are handled gracefully and skipped.
+- **Directory listing**: `@{path/to/dir}` is traversed and each file present
+  within the directory and all subdirectories is inserted into the prompt. This
+  respects `.gitignore` and `.geminiignore` if enabled.
+- **Workspace-aware**: The command searches for the path in the current
+  directory and any other workspace directories. Absolute paths are allowed if
+  they are within the workspace.
+- **Processing order**: File content injection with `@{...}` is processed
+  _before_ shell commands (`!{...}`) and argument substitution (`{{args}}`).
+- **Parsing**: The parser requires the content inside `@{...}` (the path) to
+  have balanced braces (`{` and `}`).
+
+**Example (`review.toml`):**
+
+This command injects the content of a _fixed_ best practices file
+(`docs/best-practices.md`) and uses the user's arguments to provide context for
+the review.
+
+```toml
+# In: <project>/.gemini/commands/review.toml
+# Invoked via: /review FileCommandLoader.ts
+
+description = "Reviews the provided context using a best practice guide."
+prompt = """
+You are an expert code reviewer.
+
+Your task is to review {{args}}.
+
+Use the following best practices when providing your review:
+
+@{docs/best-practices.md}
+"""
+```
+
+When you run `/review FileCommandLoader.ts`, the `@{docs/best-practices.md}`
+placeholder is replaced by the content of that file, and `{{args}}` is replaced
+by the text you provided, before the final prompt is sent 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.
+
+```bash
+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.
+
+```toml
+# 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.