@mmmbuto/gemini-cli-termux 0.30.3-termux → 0.30.5-termux

package/packages/core/dist/docs/tools/mcp-server.md

@@ -101,8 +101,8 @@ execution.
 
 #### Global MCP settings (`mcp`)
 
-The `mcp` object in your `settings.json` allows you to define global rules for
-all MCP servers.
+The `mcp` object in your `settings.json` lets you define global rules for all
+MCP servers.
 
 - **`mcp.serverCommand`** (string): A global command to start an MCP server.
 - **`mcp.allowed`** (array of strings): A list of MCP server names to allow. If
@@ -163,7 +163,8 @@ Each server configuration supports the following properties:
 - **`args`** (string[]): Command-line arguments for Stdio transport
 - **`headers`** (object): Custom HTTP headers when using `url` or `httpUrl`
 - **`env`** (object): Environment variables for the server process. Values can
-  reference environment variables using `$VAR_NAME` or `${VAR_NAME}` syntax
+  reference environment variables using `$VAR_NAME` or `${VAR_NAME}` syntax (all
+  platforms), or `%VAR_NAME%` (Windows only).
 - **`cwd`** (string): Working directory for Stdio transport
 - **`timeout`** (number): Request timeout in milliseconds (default: 600,000ms =
   10 minutes)
@@ -184,6 +185,63 @@ Each server configuration supports the following properties:
   Service Account to impersonate. Used with
   `authProviderType: 'service_account_impersonation'`.
 
+### Environment variable expansion
+
+Gemini CLI automatically expands environment variables in the `env` block of
+your MCP server configuration. This allows you to securely reference variables
+defined in your shell or environment without hardcoding sensitive information
+directly in your `settings.json` file.
+
+The expansion utility supports:
+
+- **POSIX/Bash syntax:** `$VARIABLE_NAME` or `${VARIABLE_NAME}` (supported on
+  all platforms)
+- **Windows syntax:** `%VARIABLE_NAME%` (supported only when running on Windows)
+
+If a variable is not defined in the current environment, it resolves to an empty
+string.
+
+**Example:**
+
+```json
+"env": {
+  "API_KEY": "$MY_EXTERNAL_TOKEN",
+  "LOG_LEVEL": "$LOG_LEVEL",
+  "TEMP_DIR": "%TEMP%"
+}
+```
+
+### Security and environment sanitization
+
+To protect your credentials, Gemini CLI performs environment sanitization when
+spawning MCP server processes.
+
+#### Automatic redaction
+
+By default, the CLI redacts sensitive environment variables from the base
+environment (inherited from the host process) to prevent unintended exposure to
+third-party MCP servers. This includes:
+
+- Core project keys: `GEMINI_API_KEY`, `GOOGLE_API_KEY`, etc.
+- Variables matching sensitive patterns: `*TOKEN*`, `*SECRET*`, `*PASSWORD*`,
+  `*KEY*`, `*AUTH*`, `*CREDENTIAL*`.
+- Certificates and private key patterns.
+
+#### Explicit overrides
+
+If an environment variable must be passed to an MCP server, you must explicitly
+state it in the `env` property of the server configuration in `settings.json`.
+Explicitly defined variables (including those from extensions) are trusted and
+are **not** subjected to the automatic redaction process.
+
+This follows the security principle that if a variable is explicitly configured
+by the user for a specific server, it constitutes informed consent to share that
+specific data with that server.
+
+> **Note:** Even when explicitly defined, you should avoid hardcoding secrets.
+> Instead, use environment variable expansion (e.g., `"MY_KEY": "$MY_KEY"`) to
+> securely pull the value from your host environment at runtime.
+
 ### OAuth support for remote MCP servers
 
 The Gemini CLI supports OAuth 2.0 authentication for remote MCP servers using
@@ -738,22 +796,13 @@ The MCP integration tracks several states:
 - **Trust settings:** The `trust` option bypasses all confirmation dialogs. Use
   cautiously and only for servers you completely control
 - **Access tokens:** Be security-aware when configuring environment variables
-  containing API keys or tokens
-- **Environment variable redaction:** By default, the Gemini CLI redacts
-  sensitive environment variables (such as `GEMINI_API_KEY`, `GOOGLE_API_KEY`,
-  and variables matching patterns like `*TOKEN*`, `*SECRET*`, `*PASSWORD*`) when
-  spawning MCP servers using the `stdio` transport. This prevents unintended
-  exposure of your credentials to third-party servers.
-- **Explicit environment variables:** If you need to pass a specific environment
-  variable to an MCP server, you should define it explicitly in the `env`
-  property of the server configuration in `settings.json`.
+  containing API keys or tokens. See
+  [Security and environment sanitization](#security-and-environment-sanitization)
+  for details on how Gemini CLI protects your credentials.
 - **Sandbox compatibility:** When using sandboxing, ensure MCP servers are
-  available within the sandbox environment.
+  available within the sandbox environment
 - **Private data:** Using broadly scoped personal access tokens can lead to
   information leakage between repositories.
-- **Untrusted servers:** Be extremely cautious when adding MCP servers from
-  untrusted or third-party sources. Malicious servers could attempt to
-  exfiltrate data or perform unauthorized actions through the tools they expose.
 
 ### Performance and resource management
 

package/packages/core/dist/docs/tools/memory.md

@@ -1,54 +1,35 @@
 # Memory tool (`save_memory`)
 
-This document describes the `save_memory` tool for the Gemini CLI.
+The `save_memory` tool allows the Gemini agent to persist specific facts, user
+preferences, and project details across sessions.
 
-## Description
+## Technical reference
 
-Use `save_memory` to save and recall information across your Gemini CLI
-sessions. With `save_memory`, you can direct the CLI to remember key details
-across sessions, providing personalized and directed assistance.
+This tool appends information to the `## Gemini Added Memories` section of your
+global `GEMINI.md` file (typically located at `~/.gemini/GEMINI.md`).
 
 ### Arguments
 
-`save_memory` takes one argument:
-
-- `fact` (string, required): The specific fact or piece of information to
-  remember. This should be a clear, self-contained statement written in natural
+- `fact` (string, required): A clear, self-contained statement in natural
   language.
 
-## How to use `save_memory` with the Gemini CLI
-
-The tool appends the provided `fact` to a special `GEMINI.md` file located in
-the user's home directory (`~/.gemini/GEMINI.md`). This file can be configured
-to have a different name.
-
-Once added, the facts are stored under a `## Gemini Added Memories` section.
-This file is loaded as context in subsequent sessions, allowing the CLI to
-recall the saved information.
-
-Usage:
-
-```
-save_memory(fact="Your fact here.")
-```
-
-### `save_memory` examples
-
-Remember a user preference:
+## Technical behavior
 
-```
-save_memory(fact="My preferred programming language is Python.")
-```
+- **Storage:** Appends to the global context file in the user's home directory.
+- **Loading:** The stored facts are automatically included in the hierarchical
+  context system for all future sessions.
+- **Format:** Saves data as a bulleted list item within a dedicated Markdown
+  section.
 
-Store a project-specific detail:
+## Use cases
 
-```
-save_memory(fact="The project I'm currently working on is called 'gemini-cli'.")
-```
+- Persisting user preferences (for example, "I prefer functional programming").
+- Saving project-wide architectural decisions.
+- Storing frequently used aliases or system configurations.
 
-## Important notes
+## Next steps
 
-- **General usage:** This tool should be used for concise, important facts. It
-  is not intended for storing large amounts of data or conversational history.
-- **Memory file:** The memory file is a plain text Markdown file, so you can
-  view and edit it manually if needed.
+- Follow the [Memory management guide](../cli/tutorials/memory-management.md)
+  for practical examples.
+- Learn how the [Project context (GEMINI.md)](../cli/gemini-md.md) system loads
+  this information.

package/packages/core/dist/docs/tools/planning.md

@@ -0,0 +1,57 @@
+# Gemini CLI planning tools
+
+Planning tools allow the Gemini model to switch into a safe, read-only "Plan
+Mode" for researching and planning complex changes, and to signal the
+finalization of a plan to the user.
+
+## 1. `enter_plan_mode` (EnterPlanMode)
+
+`enter_plan_mode` switches the CLI to Plan Mode. This tool is typically called
+by the agent when you ask it to "start a plan" using natural language. In this
+mode, the agent is restricted to read-only tools to allow for safe exploration
+and planning.
+
+> **Note:** This tool is not available when the CLI is in YOLO mode.
+
+- **Tool name:** `enter_plan_mode`
+- **Display name:** Enter Plan Mode
+- **File:** `enter-plan-mode.ts`
+- **Parameters:**
+  - `reason` (string, optional): A short reason explaining why the agent is
+    entering plan mode (e.g., "Starting a complex feature implementation").
+- **Behavior:**
+  - Switches the CLI's approval mode to `PLAN`.
+  - Notifies the user that the agent has entered Plan Mode.
+- **Output (`llmContent`):** A message indicating the switch, e.g.,
+  `Switching to Plan mode.`
+- **Confirmation:** Yes. The user is prompted to confirm entering Plan Mode.
+
+## 2. `exit_plan_mode` (ExitPlanMode)
+
+`exit_plan_mode` signals that the planning phase is complete. It presents the
+finalized plan to the user and requests approval to start the implementation.
+
+- **Tool name:** `exit_plan_mode`
+- **Display name:** Exit Plan Mode
+- **File:** `exit-plan-mode.ts`
+- **Parameters:**
+  - `plan_path` (string, required): The path to the finalized Markdown plan
+    file. This file MUST be located within the project's temporary plans
+    directory (e.g., `~/.gemini/tmp/<project>/plans/`).
+- **Behavior:**
+  - Validates that the `plan_path` is within the allowed directory and that the
+    file exists and has content.
+  - Presents the plan to the user for review.
+  - If the user approves the plan:
+    - Switches the CLI's approval mode to the user's chosen approval mode (
+      `DEFAULT` or `AUTO_EDIT`).
+    - Marks the plan as approved for implementation.
+  - If the user rejects the plan:
+    - Stays in Plan Mode.
+    - Returns user feedback to the model to refine the plan.
+- **Output (`llmContent`):**
+  - On approval: A message indicating the plan was approved and the new approval
+    mode.
+  - On rejection: A message containing the user's feedback.
+- **Confirmation:** Yes. Shows the finalized plan and asks for user approval to
+  proceed with implementation.

package/packages/core/dist/docs/tools/shell.md

@@ -1,70 +1,33 @@
 # Shell tool (`run_shell_command`)
 
-This document describes the `run_shell_command` tool for the Gemini CLI.
+The `run_shell_command` tool allows the Gemini model to execute commands
+directly on your system's shell. It is the primary mechanism for the agent to
+interact with your environment beyond simple file edits.
 
-## Description
+## Technical reference
 
-Use `run_shell_command` to interact with the underlying system, run scripts, or
-perform command-line operations. `run_shell_command` executes a given shell
-command, including interactive commands that require user input (e.g., `vim`,
-`git rebase -i`) if the `tools.shell.enableInteractiveShell` setting is set to
-`true`.
-
-On Windows, commands are executed with `powershell.exe -NoProfile -Command`
-(unless you explicitly point `ComSpec` at another shell). On other platforms,
-they are executed with `bash -c`.
+On Windows, commands execute with `powershell.exe -NoProfile -Command`. On other
+platforms, they execute with `bash -c`.
 
 ### Arguments
 
-`run_shell_command` takes the following arguments:
-
 - `command` (string, required): The exact shell command to execute.
-- `description` (string, optional): A brief description of the command's
-  purpose, which will be shown to the user.
-- `directory` (string, optional): The directory (relative to the project root)
-  in which to execute the command. If not provided, the command runs in the
-  project root.
-
-## How to use `run_shell_command` with the Gemini CLI
+- `description` (string, optional): A brief description shown to the user for
+  confirmation.
+- `dir_path` (string, optional): The absolute path or relative path from
+  workspace root where the command runs.
+- `is_background` (boolean, optional): Whether to move the process to the
+  background immediately after starting.
 
-When using `run_shell_command`, the command is executed as a subprocess.
-`run_shell_command` can start background processes using `&`. The tool returns
-detailed information about the execution, including:
+### Return values
 
-- `Command`: The command that was executed.
-- `Directory`: The directory where the command was run.
-- `Stdout`: Output from the standard output stream.
-- `Stderr`: Output from the standard error stream.
-- `Error`: Any error message reported by the subprocess.
-- `Exit Code`: The exit code of the command.
-- `Signal`: The signal number if the command was terminated by a signal.
-- `Background PIDs`: A list of PIDs for any background processes started.
+The tool returns a JSON object containing:
 
-Usage:
-
-```
-run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.")
-```
-
-## `run_shell_command` examples
-
-List files in the current directory:
-
-```
-run_shell_command(command="ls -la")
-```
-
-Run a script in a specific directory:
-
-```
-run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script")
-```
-
-Start a background server:
-
-```
-run_shell_command(command="npm run dev &", description="Start development server in background")
-```
+- `Command`: The executed string.
+- `Directory`: The execution path.
+- `Stdout` / `Stderr`: The output streams.
+- `Exit Code`: The process return code.
+- `Background PIDs`: PIDs of any started background processes.
 
 ## Configuration
 
@@ -167,10 +130,11 @@ configuration file.
   `"tools": {"core": ["run_shell_command(git)"]}` will only allow `git`
   commands. Including the generic `run_shell_command` acts as a wildcard,
   allowing any command not explicitly blocked.
-- `tools.exclude`: To block specific commands, add entries to the `exclude` list
-  under the `tools` category in the format `run_shell_command(<command>)`. For
-  example, `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm`
-  commands.
+- `tools.exclude` [DEPRECATED]: To block specific commands, use the
+  [Policy Engine](../reference/policy-engine.md). Historically, this setting
+  allowed adding entries to the `exclude` list under the `tools` category in the
+  format `run_shell_command(<command>)`. For example,
+  `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm` commands.
 
 The validation logic is designed to be secure and flexible:
 
@@ -223,38 +187,30 @@ To block `rm` and allow all other commands:
 If a command prefix is in both `tools.core` and `tools.exclude`, it will be
 blocked.
 
-```json
-{
-  "tools": {
-    "core": ["run_shell_command(git)"],
-    "exclude": ["run_shell_command(git push)"]
-  }
-}
-```
+- **`tools.shell.enableInteractiveShell`**: (boolean) Uses `node-pty` for
+  real-time interaction.
+- **`tools.shell.showColor`**: (boolean) Preserves ANSI colors in output.
+- **`tools.shell.inactivityTimeout`**: (number) Seconds to wait for output
+  before killing the process.
 
-- `git push origin main`: Blocked
-- `git status`: Allowed
+### Command restrictions
 
-**Block all shell commands**
+You can limit which commands the agent is allowed to request using these
+settings:
 
-To block all shell commands, add the `run_shell_command` wildcard to
-`tools.exclude`:
+- **`tools.core`**: An allowlist of command prefixes (for example,
+  `["git", "npm test"]`).
+- **`tools.exclude`**: A blocklist of command prefixes.
 
-```json
-{
-  "tools": {
-    "exclude": ["run_shell_command"]
-  }
-}
-```
+## Use cases
 
-- `ls -l`: Blocked
-- `any other command`: Blocked
+- Running build scripts and test suites.
+- Initializing or managing version control systems.
+- Installing project dependencies.
+- Starting development servers or background watchers.
 
-## Security note for `excludeTools`
+## Next steps
 
-Command-specific restrictions in `excludeTools` for `run_shell_command` are
-based on simple string matching and can be easily bypassed. This feature is
-**not a security mechanism** and should not be relied upon to safely execute
-untrusted code. It is recommended to use `coreTools` to explicitly select
-commands that can be executed.
+- Follow the [Shell commands tutorial](../cli/tutorials/shell-commands.md) for
+  practical examples.
+- Learn about [Sandboxing](../cli/sandbox.md) to isolate command execution.

package/packages/core/dist/docs/tools/todos.md

@@ -1,57 +1,35 @@
 # Todo tool (`write_todos`)
 
-This document describes the `write_todos` tool for the Gemini CLI.
+The `write_todos` tool allows the Gemini agent to maintain an internal list of
+subtasks for multi-step requests.
 
-## Description
+## Technical reference
 
-The `write_todos` tool allows the Gemini agent to create and manage a list of
-subtasks for complex user requests. This provides you, the user, with greater
-visibility into the agent's plan and its current progress. It also helps with
-alignment where the agent is less likely to lose track of its current goal.
+The agent uses this tool to manage its execution plan and provide progress
+updates to the CLI interface.
 
 ### Arguments
 
-`write_todos` takes one argument:
+- `todos` (array of objects, required): The complete list of tasks. Each object
+  includes:
+  - `description` (string): Technical description of the task.
+  - `status` (enum): `pending`, `in_progress`, `completed`, or `cancelled`.
 
-- `todos` (array of objects, required): The complete list of todo items. This
-  replaces the existing list. Each item includes:
-  - `description` (string): The task description.
-  - `status` (string): The current status (`pending`, `in_progress`,
-    `completed`, or `cancelled`).
+## Technical behavior
 
-## Behavior
+- **Interface:** Updates the progress indicator above the CLI input prompt.
+- **Exclusivity:** Only one task can be marked `in_progress` at any time.
+- **Persistence:** Todo state is scoped to the current session.
+- **Interaction:** Users can toggle the full list view using **Ctrl+T**.
 
-The agent uses this tool to break down complex multi-step requests into a clear
-plan.
+## Use cases
 
-- **Progress tracking:** The agent updates this list as it works, marking tasks
-  as `completed` when done.
-- **Single focus:** Only one task will be marked `in_progress` at a time,
-  indicating exactly what the agent is currently working on.
-- **Dynamic updates:** The plan may evolve as the agent discovers new
-  information, leading to new tasks being added or unnecessary ones being
-  cancelled.
+- Breaking down a complex feature implementation into manageable steps.
+- Coordinating multi-file refactoring tasks.
+- Providing visibility into the agent's current focus during long-running tasks.
 
-When active, the current `in_progress` task is displayed above the input box,
-keeping you informed of the immediate action. You can toggle the full view of
-the todo list at any time by pressing `Ctrl+T`.
+## Next steps
 
-Usage example (internal representation):
-
-```javascript
-write_todos({
-  todos: [
-    { description: 'Initialize new React project', status: 'completed' },
-    { description: 'Implement state management', status: 'in_progress' },
-    { description: 'Create API service', status: 'pending' },
-  ],
-});
-```
-
-## Important notes
-
-- **Enabling:** This tool is enabled by default. You can disable it in your
-  `settings.json` file by setting `"useWriteTodos": false`.
-
-- **Intended use:** This tool is primarily used by the agent for complex,
-  multi-turn tasks. It is generally not used for simple, single-turn questions.
+- Follow the [Task planning tutorial](../cli/tutorials/task-planning.md) for
+  usage details.
+- Learn about [Session management](../cli/session-management.md) for context.

package/packages/core/dist/docs/tools/web-fetch.md

@@ -1,59 +1,35 @@
 # Web fetch tool (`web_fetch`)
 
-This document describes the `web_fetch` tool for the Gemini CLI.
+The `web_fetch` tool allows the Gemini agent to retrieve and process content
+from specific URLs provided in your prompt.
 
-## Description
+## Technical reference
 
-Use `web_fetch` to summarize, compare, or extract information from web pages.
-The `web_fetch` tool processes content from one or more URLs (up to 20) embedded
-in a prompt. `web_fetch` takes a natural language prompt and returns a generated
-response.
+The agent uses this tool when you include URLs in your prompt and request
+specific operations like summarization or extraction.
 
 ### Arguments
 
-`web_fetch` takes one argument:
+- `prompt` (string, required): A request containing up to 20 valid URLs
+  (starting with `http://` or `https://`) and instructions on how to process
+  them.
 
-- `prompt` (string, required): A comprehensive prompt that includes the URL(s)
-  (up to 20) to fetch and specific instructions on how to process their content.
-  For example:
-  `"Summarize https://example.com/article and extract key points from https://another.com/data"`.
-  The prompt must contain at least one URL starting with `http://` or
-  `https://`.
+## Technical behavior
 
-## How to use `web_fetch` with the Gemini CLI
+- **Confirmation:** Triggers a confirmation dialog showing the converted URLs.
+- **Processing:** Uses the Gemini API's `urlContext` for retrieval.
+- **Fallback:** If API access fails, the tool attempts to fetch raw content
+  directly from your local machine.
+- **Formatting:** Returns a synthesized response with source attribution.
 
-To use `web_fetch` with the Gemini CLI, provide a natural language prompt that
-contains URLs. The tool will ask for confirmation before fetching any URLs. Once
-confirmed, the tool will process URLs through Gemini API's `urlContext`.
+## Use cases
 
-If the Gemini API cannot access the URL, the tool will fall back to fetching
-content directly from the local machine. The tool will format the response,
-including source attribution and citations where possible. The tool will then
-provide the response to the user.
+- Summarizing technical articles or blog posts.
+- Comparing data between two or more web pages.
+- Extracting specific information from a documentation site.
 
-Usage:
+## Next steps
 
-```
-web_fetch(prompt="Your prompt, including a URL such as https://google.com.")
-```
-
-## `web_fetch` examples
-
-Summarize a single article:
-
-```
-web_fetch(prompt="Can you summarize the main points of https://example.com/news/latest")
-```
-
-Compare two articles:
-
-```
-web_fetch(prompt="What are the differences in the conclusions of these two papers: https://arxiv.org/abs/2401.0001 and https://arxiv.org/abs/2401.0002?")
-```
-
-## Important notes
-
-- **URL processing:** `web_fetch` relies on the Gemini API's ability to access
-  and process the given URLs.
-- **Output quality:** The quality of the output will depend on the clarity of
-  the instructions in the prompt.
+- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
+  usage examples.
+- See the [Web search tool reference](./web-search.md) for general queries.

package/packages/core/dist/docs/tools/web-search.md

@@ -1,42 +1,32 @@
 # Web search tool (`google_web_search`)
 
-This document describes the `google_web_search` tool.
+The `google_web_search` tool allows the Gemini agent to retrieve up-to-date
+information, news, and facts from the internet via Google Search.
 
-## Description
+## Technical reference
 
-Use `google_web_search` to perform a web search using Google Search via the
-Gemini API. The `google_web_search` tool returns a summary of web results with
-sources.
+The agent uses this tool when your request requires knowledge of current events
+or specific online documentation not available in its internal training data.
 
 ### Arguments
 
-`google_web_search` takes one argument:
+- `query` (string, required): The search query to be executed.
 
-- `query` (string, required): The search query.
+## Technical behavior
 
-## How to use `google_web_search` with the Gemini CLI
+- **Grounding:** Returns a generated summary based on search results.
+- **Citations:** Includes source URIs and titles for factual grounding.
+- **Processing:** The Gemini API processes the search results before returning a
+  synthesized response to the agent.
 
-The `google_web_search` tool sends a query to the Gemini API, which then
-performs a web search. `google_web_search` will return a generated response
-based on the search results, including citations and sources.
+## Use cases
 
-Usage:
+- Researching the latest version of a software library or API.
+- Finding solutions to recent software bugs or security vulnerabilities.
+- Retrieving news or documentation updated after the model's knowledge cutoff.
 
-```
-google_web_search(query="Your query goes here.")
-```
+## Next steps
 
-## `google_web_search` examples
-
-Get information on a topic:
-
-```
-google_web_search(query="latest advancements in AI-powered code generation")
-```
-
-## Important notes
-
-- **Response returned:** The `google_web_search` tool returns a processed
-  summary, not a raw list of search results.
-- **Citations:** The response includes citations to the sources used to generate
-  the summary.
+- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
+  usage examples.
+- Explore the [Web fetch tool reference](./web-fetch.md) for direct URL access.