Merge branch 'google-gemini:main' into main

Author: akabarki76

docs/cli/commands.md

@@ -129,6 +129,67 @@ Your command definition files must be written in the TOML format and use the `.t
 
 - `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, 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 `{{args}}`
+
+If your `prompt` contains the special placeholder `{{args}}`, 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`):**
+
+```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: {{args}}."
+```
+
+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 `{{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.
+
 ---
 
 #### Example: A "Pure Function" Refactoring Command
@@ -175,11 +236,6 @@ That's it! You can now run your command in the CLI. First, you might add a file
 
 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.

docs/cli/configuration.md

@@ -429,7 +429,7 @@ This example demonstrates how you can provide general project context, specific
       - Location: The CLI searches for the configured context file in the current working directory and then in each parent directory up to either the project root (identified by a `.git` folder) or your home directory.
       - Scope: Provides context relevant to the entire project or a significant portion of it.
   3.  **Sub-directory Context Files (Contextual/Local):**
-      - Location: The CLI also scans for the configured context file in subdirectories _below_ the current working directory (respecting common ignore patterns like `node_modules`, `.git`, etc.).
+      - Location: The CLI also scans for the configured context file in subdirectories _below_ the current working directory (respecting common ignore patterns like `node_modules`, `.git`, etc.). The breadth of this search is limited to 200 directories by default, but can be configured with a `memoryDiscoveryMaxDirs` field in your `settings.json` file.
       - Scope: Allows for highly specific instructions relevant to a particular component, module, or subsection of your project.
 - **Concatenation & UI Indication:** The contents of all found context files are concatenated (with separators indicating their origin and path) and provided as part of the system prompt to the Gemini model. The CLI footer displays the count of loaded context files, giving you a quick visual cue about the active instructional context.
 - **Commands for Memory Management:**

docs/telemetry.md

@@ -19,6 +19,7 @@ The following lists the precedence for applying telemetry settings, with items l
     - `--telemetry-target <local|gcp>`: Overrides `telemetry.target`.
     - `--telemetry-otlp-endpoint <URL>`: Overrides `telemetry.otlpEndpoint`.
     - `--telemetry-log-prompts` / `--no-telemetry-log-prompts`: Overrides `telemetry.logPrompts`.
+    - `--telemetry-outfile <path>`: Redirects telemetry output to a file. See [Exporting to a file](#exporting-to-a-file).
 
 1.  **Environment variables:**
     - `OTEL_EXPORTER_OTLP_ENDPOINT`: Overrides `telemetry.otlpEndpoint`.
@@ -50,6 +51,16 @@ The following code can be added to your workspace (`.gemini/settings.json`) or u
 }
 ```
 
+### Exporting to a file
+
+You can export all telemetry data to a file for local inspection.
+
+To enable file export, use the `--telemetry-outfile` flag with a path to your desired output file. This must be run using `--telemetry-target=local`.
+
+```bash
+gemini --telemetry --telemetry-target=local --telemetry-outfile=/path/to/telemetry.log "your prompt"
+```
+
 ## Running an OTEL Collector
 
 An OTEL Collector is a service that receives, processes, and exports telemetry data.

packages/cli/src/config/config.test.ts

@@ -37,7 +37,7 @@ vi.mock('@google/gemini-cli-core', async () => {
     ...actualServer,
     loadEnvironment: vi.fn(),
     loadServerHierarchicalMemory: vi.fn(
-      (cwd, debug, fileService, extensionPaths) =>
+      (cwd, debug, fileService, extensionPaths, _maxDirs) =>
         Promise.resolve({
           memoryContent: extensionPaths?.join(',') || '',
           fileCount: extensionPaths?.length || 0,
@@ -491,6 +491,7 @@ describe('Hierarchical Memory Loading (config.ts) - Placeholder Suite', () => {
         respectGitIgnore: false,
         respectGeminiIgnore: true,
       },
+      undefined, // maxDirs
     );
   });
 

packages/cli/src/config/config.ts

@@ -55,6 +55,7 @@ export interface CliArgs {
   telemetryTarget: string | undefined;
   telemetryOtlpEndpoint: string | undefined;
   telemetryLogPrompts: boolean | undefined;
+  telemetryOutfile: string | undefined;
   allowedMcpServerNames: string[] | undefined;
   experimentalAcp: boolean | undefined;
   extensions: string[] | undefined;
@@ -159,6 +160,10 @@ export async function parseArguments(): Promise<CliArgs> {
       description:
         'Enable or disable logging of user prompts for telemetry. Overrides settings files.',
     })
+    .option('telemetry-outfile', {
+      type: 'string',
+      description: 'Redirect all telemetry output to the specified file.',
+    })
     .option('checkpointing', {
       alias: 'c',
       type: 'boolean',
@@ -220,6 +225,7 @@ export async function loadHierarchicalGeminiMemory(
   currentWorkingDirectory: string,
   debugMode: boolean,
   fileService: FileDiscoveryService,
+  settings: Settings,
   extensionContextFilePaths: string[] = [],
   fileFilteringOptions?: FileFilteringOptions,
 ): Promise<{ memoryContent: string; fileCount: number }> {
@@ -237,6 +243,7 @@ export async function loadHierarchicalGeminiMemory(
     fileService,
     extensionContextFilePaths,
     fileFilteringOptions,
+    settings.memoryDiscoveryMaxDirs,
   );
 }
 
@@ -293,6 +300,7 @@ export async function loadCliConfig(
     process.cwd(),
     debugMode,
     fileService,
+    settings,
     extensionContextFilePaths,
     fileFiltering,
   );
@@ -412,6 +420,7 @@ export async function loadCliConfig(
         process.env.OTEL_EXPORTER_OTLP_ENDPOINT ??
         settings.telemetry?.otlpEndpoint,
       logPrompts: argv.telemetryLogPrompts ?? settings.telemetry?.logPrompts,
+      outfile: argv.telemetryOutfile ?? settings.telemetry?.outfile,
     },
     usageStatisticsEnabled: settings.usageStatisticsEnabled ?? true,
     // Git-aware file filtering settings

packages/cli/src/config/settings.ts

@@ -100,6 +100,7 @@ export interface Settings {
 
   // Add other settings here.
   ideMode?: boolean;
+  memoryDiscoveryMaxDirs?: number;
 }
 
 export interface SettingsError {

packages/cli/src/services/FileCommandLoader.test.ts

@@ -14,8 +14,6 @@ import mock from 'mock-fs';
 import { assert } from 'vitest';
 import { createMockCommandContext } from '../test-utils/mockCommandContext.js';
 
-const mockContext = createMockCommandContext();
-
 describe('FileCommandLoader', () => {
   const signal: AbortSignal = new AbortController().signal;
 
@@ -39,7 +37,16 @@ describe('FileCommandLoader', () => {
     expect(command).toBeDefined();
     expect(command.name).toBe('test');
 
-    const result = await command.action?.(mockContext, '');
+    const result = await command.action?.(
+      createMockCommandContext({
+        invocation: {
+          raw: '/test',
+          name: 'test',
+          args: '',
+        },
+      }),
+      '',
+    );
     if (result?.type === 'submit_prompt') {
       expect(result.content).toBe('This is a test prompt');
     } else {
@@ -122,7 +129,16 @@ describe('FileCommandLoader', () => {
     const command = commands[0];
     expect(command).toBeDefined();
 
-    const result = await command.action?.(mockContext, '');
+    const result = await command.action?.(
+      createMockCommandContext({
+        invocation: {
+          raw: '/test',
+          name: 'test',
+          args: '',
+        },
+      }),
+      '',
+    );
     if (result?.type === 'submit_prompt') {
       expect(result.content).toBe('Project prompt');
     } else {
@@ -232,4 +248,70 @@ describe('FileCommandLoader', () => {
     // Verify that the ':' in the filename was replaced with an '_'
     expect(command.name).toBe('legacy_command');
   });
+
+  describe('Shorthand Argument Processor Integration', () => {
+    it('correctly processes a command with {{args}}', async () => {
+      const userCommandsDir = getUserCommandsDir();
+      mock({
+        [userCommandsDir]: {
+          'shorthand.toml':
+            'prompt = "The user wants to: {{args}}"\ndescription = "Shorthand test"',
+        },
+      });
+
+      const loader = new FileCommandLoader(null as unknown as Config);
+      const commands = await loader.loadCommands(signal);
+      const command = commands.find((c) => c.name === 'shorthand');
+      expect(command).toBeDefined();
+
+      const result = await command!.action?.(
+        createMockCommandContext({
+          invocation: {
+            raw: '/shorthand do something cool',
+            name: 'shorthand',
+            args: 'do something cool',
+          },
+        }),
+        'do something cool',
+      );
+      expect(result?.type).toBe('submit_prompt');
+      if (result?.type === 'submit_prompt') {
+        expect(result.content).toBe('The user wants to: do something cool');
+      }
+    });
+  });
+
+  describe('Default Argument Processor Integration', () => {
+    it('correctly processes a command without {{args}}', async () => {
+      const userCommandsDir = getUserCommandsDir();
+      mock({
+        [userCommandsDir]: {
+          'model_led.toml':
+            'prompt = "This is the instruction."\ndescription = "Default processor test"',
+        },
+      });
+
+      const loader = new FileCommandLoader(null as unknown as Config);
+      const commands = await loader.loadCommands(signal);
+      const command = commands.find((c) => c.name === 'model_led');
+      expect(command).toBeDefined();
+
+      const result = await command!.action?.(
+        createMockCommandContext({
+          invocation: {
+            raw: '/model_led 1.2.0 added "a feature"',
+            name: 'model_led',
+            args: '1.2.0 added "a feature"',
+          },
+        }),
+        '1.2.0 added "a feature"',
+      );
+      expect(result?.type).toBe('submit_prompt');
+      if (result?.type === 'submit_prompt') {
+        const expectedContent =
+          'This is the instruction.\n\n/model_led 1.2.0 added "a feature"';
+        expect(result.content).toBe(expectedContent);
+      }
+    });
+  });
 });

packages/cli/src/services/FileCommandLoader.ts

@@ -15,7 +15,20 @@ import {
   getUserCommandsDir,
 } from '@google/gemini-cli-core';
 import { ICommandLoader } from './types.js';
-import { CommandKind, SlashCommand } from '../ui/commands/types.js';
+import {
+  CommandContext,
+  CommandKind,
+  SlashCommand,
+  SubmitPromptActionReturn,
+} from '../ui/commands/types.js';
+import {
+  DefaultArgumentProcessor,
+  ShorthandArgumentProcessor,
+} from './prompt-processors/argumentProcessor.js';
+import {
+  IPromptProcessor,
+  SHORTHAND_ARGS_PLACEHOLDER,
+} from './prompt-processors/types.js';
 
 /**
  * Defines the Zod schema for a command definition file. This serves as the
@@ -156,16 +169,45 @@ export class FileCommandLoader implements ICommandLoader {
       .map((segment) => segment.replaceAll(':', '_'))
       .join(':');
 
+    const processors: IPromptProcessor[] = [];
+
+    // The presence of '{{args}}' is the switch that determines the behavior.
+    if (validDef.prompt.includes(SHORTHAND_ARGS_PLACEHOLDER)) {
+      processors.push(new ShorthandArgumentProcessor());
+    } else {
+      processors.push(new DefaultArgumentProcessor());
+    }
+
     return {
       name: commandName,
       description:
         validDef.description ||
         `Custom command from ${path.basename(filePath)}`,
       kind: CommandKind.FILE,
-      action: async () => ({
-        type: 'submit_prompt',
-        content: validDef.prompt,
-      }),
+      action: async (
+        context: CommandContext,
+        _args: string,
+      ): Promise<SubmitPromptActionReturn> => {
+        if (!context.invocation) {
+          console.error(
+            `[FileCommandLoader] Critical error: Command '${commandName}' was executed without invocation context.`,
+          );
+          return {
+            type: 'submit_prompt',
+            content: validDef.prompt, // Fallback to unprocessed prompt
+          };
+        }
+
+        let processedPrompt = validDef.prompt;
+        for (const processor of processors) {
+          processedPrompt = await processor.process(processedPrompt, context);
+        }
+
+        return {
+          type: 'submit_prompt',
+          content: processedPrompt,
+        };
+      },
     };
   }
 }