Merge branch 'main' into main

Author: akabarki76

.github/workflows/e2e.yml

@@ -8,8 +8,8 @@ on:
   merge_group:
 
 jobs:
-  e2e-test:
-    name: E2E Test - ${{ matrix.sandbox }}
+  e2e-test-linux:
+    name: E2E Test (Linux) - ${{ matrix.sandbox }}
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -47,3 +47,27 @@ jobs:
         env:
           GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
         run: npm run test:integration:${{ matrix.sandbox }} -- --verbose --keep-output
+
+  e2e-test-macos:
+    name: E2E Test - macOS
+    runs-on: macos-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 20.x
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Run E2E tests
+        env:
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+        run: npm run test:e2e

docs/cli/commands.md

@@ -6,6 +6,8 @@ Gemini CLI supports several built-in commands to help you manage your session, c
 
 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 `bugCommand` setting in your `.gemini/settings.json` files.
 
@@ -38,7 +40,7 @@ Slash commands provide meta-level control over the CLI itself.
   - **Description:** Lists all active extensions in the current Gemini CLI session. See [Gemini CLI Extensions](../extension.md).
 
 - **`/help`** (or **`/?`**)
-  - **Description:** Display help information about the Gemini CLI, including available commands and their usage.
+  - **Description:** Display help information about Gemini CLI, including available commands and their usage.
 
 - **`/mcp`**
   - **Description:** List configured Model Context Protocol (MCP) servers, their connection status, server details, and available tools.
@@ -93,6 +95,91 @@ Slash commands provide meta-level control over the CLI itself.
 - **`/quit`** (or **`/exit`**)
   - **Description:** Exit Gemini CLI.
 
+### Custom Commands
+
+For a quick start, see the [example](#example-a-pure-function-refactoring-command) 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 (`:`).
+
+- 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.**
+
+---
+
+#### 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.
+
+This initial version of custom commands is focused on static prompts. Future updates are planned to introduce more dynamic capabilities, including:
+
+- **Argument Support:** Passing arguments from the command line directly into your `prompt` template.
+- **Shell Execution:** Creating commands that can run local shell scripts to gather context before running the 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.

package-lock.json

@@ -60,6 +60,7 @@
     "@types/micromatch": "^4.0.9",
     "@types/mime-types": "^3.0.1",
     "@types/minimatch": "^5.1.2",
+    "@types/mock-fs": "^4.13.4",
     "@types/shell-quote": "^1.7.5",
     "@vitest/coverage-v8": "^3.1.1",
     "concurrently": "^9.2.0",
@@ -76,6 +77,7 @@
     "json": "^11.0.0",
     "lodash": "^4.17.21",
     "memfs": "^4.17.2",
+    "mock-fs": "^5.5.0",
     "prettier": "^3.5.3",
     "react-devtools-core": "^4.28.5",
     "typescript-eslint": "^8.30.1",

package.json

@@ -29,6 +29,7 @@
   },
   "dependencies": {
     "@google/gemini-cli-core": "file:../core",
+    "@iarna/toml": "^2.2.5",
     "@types/update-notifier": "^6.0.8",
     "command-exists": "^1.2.9",
     "diff": "^7.0.0",

packages/cli/package.json

@@ -72,7 +72,7 @@ describe('BuiltinCommandLoader', () => {
 
   it('should correctly pass the config object to command factory functions', async () => {
     const loader = new BuiltinCommandLoader(mockConfig);
-    await loader.loadCommands();
+    await loader.loadCommands(new AbortController().signal);
 
     expect(ideCommandMock).toHaveBeenCalledTimes(1);
     expect(ideCommandMock).toHaveBeenCalledWith(mockConfig);
@@ -84,7 +84,7 @@ describe('BuiltinCommandLoader', () => {
     // Override the mock's behavior for this specific test.
     ideCommandMock.mockReturnValue(null);
     const loader = new BuiltinCommandLoader(mockConfig);
-    const commands = await loader.loadCommands();
+    const commands = await loader.loadCommands(new AbortController().signal);
 
     // The 'ide' command should be filtered out.
     const ideCmd = commands.find((c) => c.name === 'ide');
@@ -97,7 +97,7 @@ describe('BuiltinCommandLoader', () => {
 
   it('should handle a null config gracefully when calling factories', async () => {
     const loader = new BuiltinCommandLoader(null);
-    await loader.loadCommands();
+    await loader.loadCommands(new AbortController().signal);
     expect(ideCommandMock).toHaveBeenCalledTimes(1);
     expect(ideCommandMock).toHaveBeenCalledWith(null);
     expect(restoreCommandMock).toHaveBeenCalledTimes(1);
@@ -106,7 +106,7 @@ describe('BuiltinCommandLoader', () => {
 
   it('should return a list of all loaded commands', async () => {
     const loader = new BuiltinCommandLoader(mockConfig);
-    const commands = await loader.loadCommands();
+    const commands = await loader.loadCommands(new AbortController().signal);
 
     const aboutCmd = commands.find((c) => c.name === 'about');
     expect(aboutCmd).toBeDefined();