@didim365/agent-cli-core 0.1.1 → 0.1.3

package/dist/docs/cli/enterprise.md

@@ -1,565 +0,0 @@
-# Gemini CLI for the enterprise
-
-This document outlines configuration patterns and best practices for deploying
-and managing Gemini CLI in an enterprise environment. By leveraging system-level
-settings, administrators can enforce security policies, manage tool access, and
-ensure a consistent experience for all users.
-
-> **A note on security:** The patterns described in this document are intended
-> to help administrators create a more controlled and secure environment for
-> using Gemini CLI. However, they should not be considered a foolproof security
-> boundary. A determined user with sufficient privileges on their local machine
-> may still be able to circumvent these configurations. These measures are
-> designed to prevent accidental misuse and enforce corporate policy in a
-> managed environment, not to defend against a malicious actor with local
-> administrative rights.
-
-## Centralized configuration: The system settings file
-
-The most powerful tools for enterprise administration are the system-wide
-settings files. These files allow you to define a baseline configuration
-(`system-defaults.json`) and a set of overrides (`settings.json`) that apply to
-all users on a machine. For a complete overview of configuration options, see
-the [Configuration documentation](../get-started/configuration.md).
-
-Settings are merged from four files. The precedence order for single-value
-settings (like `theme`) is:
-
-1. System Defaults (`system-defaults.json`)
-2. User Settings (`~/.gemini/settings.json`)
-3. Workspace Settings (`<project>/.gemini/settings.json`)
-4. System Overrides (`settings.json`)
-
-This means the System Overrides file has the final say. For settings that are
-arrays (`includeDirectories`) or objects (`mcpServers`), the values are merged.
-
-**Example of merging and precedence:**
-
-Here is how settings from different levels are combined.
-
-- **System defaults `system-defaults.json`:**
-
-  ```json
-  {
-    "ui": {
-      "theme": "default-corporate-theme"
-    },
-    "context": {
-      "includeDirectories": ["/etc/gemini-cli/common-context"]
-    }
-  }
-  ```
-
-- **User `settings.json` (`~/.gemini/settings.json`):**
-
-  ```json
-  {
-    "ui": {
-      "theme": "user-preferred-dark-theme"
-    },
-    "mcpServers": {
-      "corp-server": {
-        "command": "/usr/local/bin/corp-server-dev"
-      },
-      "user-tool": {
-        "command": "npm start --prefix ~/tools/my-tool"
-      }
-    },
-    "context": {
-      "includeDirectories": ["~/gemini-context"]
-    }
-  }
-  ```
-
-- **Workspace `settings.json` (`<project>/.gemini/settings.json`):**
-
-  ```json
-  {
-    "ui": {
-      "theme": "project-specific-light-theme"
-    },
-    "mcpServers": {
-      "project-tool": {
-        "command": "npm start"
-      }
-    },
-    "context": {
-      "includeDirectories": ["./project-context"]
-    }
-  }
-  ```
-
-- **System overrides `settings.json`:**
-  ```json
-  {
-    "ui": {
-      "theme": "system-enforced-theme"
-    },
-    "mcpServers": {
-      "corp-server": {
-        "command": "/usr/local/bin/corp-server-prod"
-      }
-    },
-    "context": {
-      "includeDirectories": ["/etc/gemini-cli/global-context"]
-    }
-  }
-  ```
-
-This results in the following merged configuration:
-
-- **Final merged configuration:**
-  ```json
-  {
-    "ui": {
-      "theme": "system-enforced-theme"
-    },
-    "mcpServers": {
-      "corp-server": {
-        "command": "/usr/local/bin/corp-server-prod"
-      },
-      "user-tool": {
-        "command": "npm start --prefix ~/tools/my-tool"
-      },
-      "project-tool": {
-        "command": "npm start"
-      }
-    },
-    "context": {
-      "includeDirectories": [
-        "/etc/gemini-cli/common-context",
-        "~/gemini-context",
-        "./project-context",
-        "/etc/gemini-cli/global-context"
-      ]
-    }
-  }
-  ```
-
-**Why:**
-
-- **`theme`**: The value from the system overrides (`system-enforced-theme`) is
-  used, as it has the highest precedence.
-- **`mcpServers`**: The objects are merged. The `corp-server` definition from
-  the system overrides takes precedence over the user's definition. The unique
-  `user-tool` and `project-tool` are included.
-- **`includeDirectories`**: The arrays are concatenated in the order of System
-  Defaults, User, Workspace, and then System Overrides.
-
-- **Location**:
-  - **Linux**: `/etc/gemini-cli/settings.json`
-  - **Windows**: `C:\ProgramData\gemini-cli\settings.json`
-  - **macOS**: `/Library/Application Support/GeminiCli/settings.json`
-  - The path can be overridden using the `GEMINI_CLI_SYSTEM_SETTINGS_PATH`
-    environment variable.
-- **Control**: This file should be managed by system administrators and
-  protected with appropriate file permissions to prevent unauthorized
-  modification by users.
-
-By using the system settings file, you can enforce the security and
-configuration patterns described below.
-
-### Enforcing system settings with a wrapper script
-
-While the `GEMINI_CLI_SYSTEM_SETTINGS_PATH` environment variable provides
-flexibility, a user could potentially override it to point to a different
-settings file, bypassing the centrally managed configuration. To mitigate this,
-enterprises can deploy a wrapper script or alias that ensures the environment
-variable is always set to the corporate-controlled path.
-
-This approach ensures that no matter how the user calls the `gemini` command,
-the enterprise settings are always loaded with the highest precedence.
-
-**Example wrapper script:**
-
-Administrators can create a script named `gemini` and place it in a directory
-that appears earlier in the user's `PATH` than the actual Gemini CLI binary
-(e.g., `/usr/local/bin/gemini`).
-
-```bash
-#!/bin/bash
-
-# Enforce the path to the corporate system settings file.
-# This ensures that the company's configuration is always applied.
-export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/gemini-cli/settings.json"
-
-# Find the original gemini executable.
-# This is a simple example; a more robust solution might be needed
-# depending on the installation method.
-REAL_GEMINI_PATH=$(type -aP gemini | grep -v "^$(type -P gemini)$" | head -n 1)
-
-if [ -z "$REAL_GEMINI_PATH" ]; then
-  echo "Error: The original 'gemini' executable was not found." >&2
-  exit 1
-fi
-
-# Pass all arguments to the real Gemini CLI executable.
-exec "$REAL_GEMINI_PATH" "$@"
-```
-
-By deploying this script, the `GEMINI_CLI_SYSTEM_SETTINGS_PATH` is set within
-the script's environment, and the `exec` command replaces the script process
-with the actual Gemini CLI process, which inherits the environment variable.
-This makes it significantly more difficult for a user to bypass the enforced
-settings.
-
-## Restricting tool access
-
-You can significantly enhance security by controlling which tools the Gemini
-model can use. This is achieved through the `tools.core` and `tools.exclude`
-settings. For a list of available tools, see the
-[Tools documentation](../tools/index.md).
-
-### Allowlisting with `coreTools`
-
-The most secure approach is to explicitly add the tools and commands that users
-are permitted to execute to an allowlist. This prevents the use of any tool not
-on the approved list.
-
-**Example:** Allow only safe, read-only file operations and listing files.
-
-```json
-{
-  "tools": {
-    "core": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]
-  }
-}
-```
-
-### Blocklisting with `excludeTools`
-
-Alternatively, you can add specific tools that are considered dangerous in your
-environment to a blocklist.
-
-**Example:** Prevent the use of the shell tool for removing files.
-
-```json
-{
-  "tools": {
-    "exclude": ["ShellTool(rm -rf)"]
-  }
-}
-```
-
-**Security note:** Blocklisting with `excludeTools` is less secure than
-allowlisting with `coreTools`, as it relies on blocking known-bad commands, and
-clever users may find ways to bypass simple string-based blocks. **Allowlisting
-is the recommended approach.**
-
-### Disabling YOLO mode
-
-To ensure that users cannot bypass the confirmation prompt for tool execution,
-you can disable YOLO mode at the policy level. This adds a critical layer of
-safety, as it prevents the model from executing tools without explicit user
-approval.
-
-**Example:** Force all tool executions to require user confirmation.
-
-```json
-{
-  "security": {
-    "disableYoloMode": true
-  }
-}
-```
-
-This setting is highly recommended in an enterprise environment to prevent
-unintended tool execution.
-
-## Managing custom tools (MCP servers)
-
-If your organization uses custom tools via
-[Model-Context Protocol (MCP) servers](../core/tools-api.md), it is crucial to
-understand how server configurations are managed to apply security policies
-effectively.
-
-### How MCP server configurations are merged
-
-Gemini CLI loads `settings.json` files from three levels: System, Workspace, and
-User. When it comes to the `mcpServers` object, these configurations are
-**merged**:
-
-1.  **Merging:** The lists of servers from all three levels are combined into a
-    single list.
-2.  **Precedence:** If a server with the **same name** is defined at multiple
-    levels (e.g., a server named `corp-api` exists in both system and user
-    settings), the definition from the highest-precedence level is used. The
-    order of precedence is: **System > Workspace > User**.
-
-This means a user **cannot** override the definition of a server that is already
-defined in the system-level settings. However, they **can** add new servers with
-unique names.
-
-### Enforcing a catalog of tools
-
-The security of your MCP tool ecosystem depends on a combination of defining the
-canonical servers and adding their names to an allowlist.
-
-### Restricting tools within an MCP server
-
-For even greater security, especially when dealing with third-party MCP servers,
-you can restrict which specific tools from a server are exposed to the model.
-This is done using the `includeTools` and `excludeTools` properties within a
-server's definition. This allows you to use a subset of tools from a server
-without allowing potentially dangerous ones.
-
-Following the principle of least privilege, it is highly recommended to use
-`includeTools` to create an allowlist of only the necessary tools.
-
-**Example:** Only allow the `code-search` and `get-ticket-details` tools from a
-third-party MCP server, even if the server offers other tools like
-`delete-ticket`.
-
-```json
-{
-  "mcp": {
-    "allowed": ["third-party-analyzer"]
-  },
-  "mcpServers": {
-    "third-party-analyzer": {
-      "command": "/usr/local/bin/start-3p-analyzer.sh",
-      "includeTools": ["code-search", "get-ticket-details"]
-    }
-  }
-}
-```
-
-#### More secure pattern: Define and add to allowlist in system settings
-
-To create a secure, centrally-managed catalog of tools, the system administrator
-**must** do both of the following in the system-level `settings.json` file:
-
-1.  **Define the full configuration** for every approved server in the
-    `mcpServers` object. This ensures that even if a user defines a server with
-    the same name, the secure system-level definition will take precedence.
-2.  **Add the names** of those servers to an allowlist using the `mcp.allowed`
-    setting. This is a critical security step that prevents users from running
-    any servers that are not on this list. If this setting is omitted, the CLI
-    will merge and allow any server defined by the user.
-
-**Example system `settings.json`:**
-
-1. Add the _names_ of all approved servers to an allowlist. This will prevent
-   users from adding their own servers.
-
-2. Provide the canonical _definition_ for each server on the allowlist.
-
-```json
-{
-  "mcp": {
-    "allowed": ["corp-data-api", "source-code-analyzer"]
-  },
-  "mcpServers": {
-    "corp-data-api": {
-      "command": "/usr/local/bin/start-corp-api.sh",
-      "timeout": 5000
-    },
-    "source-code-analyzer": {
-      "command": "/usr/local/bin/start-analyzer.sh"
-    }
-  }
-}
-```
-
-This pattern is more secure because it uses both definition and an allowlist.
-Any server a user defines will either be overridden by the system definition (if
-it has the same name) or blocked because its name is not in the `mcp.allowed`
-list.
-
-### Less secure pattern: Omitting the allowlist
-
-If the administrator defines the `mcpServers` object but fails to also specify
-the `mcp.allowed` allowlist, users may add their own servers.
-
-**Example system `settings.json`:**
-
-This configuration defines servers but does not enforce the allowlist. The
-administrator has NOT included the "mcp.allowed" setting.
-
-```json
-{
-  "mcpServers": {
-    "corp-data-api": {
-      "command": "/usr/local/bin/start-corp-api.sh"
-    }
-  }
-}
-```
-
-In this scenario, a user can add their own server in their local
-`settings.json`. Because there is no `mcp.allowed` list to filter the merged
-results, the user's server will be added to the list of available tools and
-allowed to run.
-
-## Enforcing sandboxing for security
-
-To mitigate the risk of potentially harmful operations, you can enforce the use
-of sandboxing for all tool execution. The sandbox isolates tool execution in a
-containerized environment.
-
-**Example:** Force all tool execution to happen within a Docker sandbox.
-
-```json
-{
-  "tools": {
-    "sandbox": "docker"
-  }
-}
-```
-
-You can also specify a custom, hardened Docker image for the sandbox by building
-a custom `sandbox.Dockerfile` as described in the
-[Sandboxing documentation](./sandbox.md).
-
-## Controlling network access via proxy
-
-In corporate environments with strict network policies, you can configure Gemini
-CLI to route all outbound traffic through a corporate proxy. This can be set via
-an environment variable, but it can also be enforced for custom tools via the
-`mcpServers` configuration.
-
-**Example (for an MCP server):**
-
-```json
-{
-  "mcpServers": {
-    "proxied-server": {
-      "command": "node",
-      "args": ["mcp_server.js"],
-      "env": {
-        "HTTP_PROXY": "http://proxy.example.com:8080",
-        "HTTPS_PROXY": "http://proxy.example.com:8080"
-      }
-    }
-  }
-}
-```
-
-## Telemetry and auditing
-
-For auditing and monitoring purposes, you can configure Gemini CLI to send
-telemetry data to a central location. This allows you to track tool usage and
-other events. For more information, see the
-[telemetry documentation](./telemetry.md).
-
-**Example:** Enable telemetry and send it to a local OTLP collector. If
-`otlpEndpoint` is not specified, it defaults to `http://localhost:4317`.
-
-```json
-{
-  "telemetry": {
-    "enabled": true,
-    "target": "gcp",
-    "logPrompts": false
-  }
-}
-```
-
-**Note:** Ensure that `logPrompts` is set to `false` in an enterprise setting to
-avoid collecting potentially sensitive information from user prompts.
-
-## Authentication
-
-You can enforce a specific authentication method for all users by setting the
-`enforcedAuthType` in the system-level `settings.json` file. This prevents users
-from choosing a different authentication method. See the
-[Authentication docs](./authentication.md) for more details.
-
-**Example:** Enforce the use of Google login for all users.
-
-```json
-{
-  "enforcedAuthType": "oauth-personal"
-}
-```
-
-If a user has a different authentication method configured, they will be
-prompted to switch to the enforced method. In non-interactive mode, the CLI will
-exit with an error if the configured authentication method does not match the
-enforced one.
-
-### Restricting logins to corporate domains
-
-For enterprises using Google Workspace, you can enforce that users only
-authenticate with their corporate Google accounts. This is a network-level
-control that is configured on a proxy server, not within Gemini CLI itself. It
-works by intercepting authentication requests to Google and adding a special
-HTTP header.
-
-This policy prevents users from logging in with personal Gmail accounts or other
-non-corporate Google accounts.
-
-For detailed instructions, see the Google Workspace Admin Help article on
-[blocking access to consumer accounts](https://support.google.com/a/answer/1668854?hl=en#zippy=%2Cstep-choose-a-web-proxy-server%2Cstep-configure-the-network-to-block-certain-accounts).
-
-The general steps are as follows:
-
-1.  **Intercept Requests**: Configure your web proxy to intercept all requests
-    to `google.com`.
-2.  **Add HTTP Header**: For each intercepted request, add the
-    `X-GoogApps-Allowed-Domains` HTTP header.
-3.  **Specify Domains**: The value of the header should be a comma-separated
-    list of your approved Google Workspace domain names.
-
-**Example header:**
-
-```
-X-GoogApps-Allowed-Domains: my-corporate-domain.com, secondary-domain.com
-```
-
-When this header is present, Google's authentication service will only allow
-logins from accounts belonging to the specified domains.
-
-## Putting it all together: example system `settings.json`
-
-Here is an example of a system `settings.json` file that combines several of the
-patterns discussed above to create a secure, controlled environment for Gemini
-CLI.
-
-```json
-{
-  "tools": {
-    "sandbox": "docker",
-    "core": [
-      "ReadFileTool",
-      "GlobTool",
-      "ShellTool(ls)",
-      "ShellTool(cat)",
-      "ShellTool(grep)"
-    ]
-  },
-  "mcp": {
-    "allowed": ["corp-tools"]
-  },
-  "mcpServers": {
-    "corp-tools": {
-      "command": "/opt/gemini-tools/start.sh",
-      "timeout": 5000
-    }
-  },
-  "telemetry": {
-    "enabled": true,
-    "target": "gcp",
-    "otlpEndpoint": "https://telemetry-prod.example.com:4317",
-    "logPrompts": false
-  },
-  "advanced": {
-    "bugCommand": {
-      "urlTemplate": "https://servicedesk.example.com/new-ticket?title={title}&details={info}"
-    }
-  },
-  "privacy": {
-    "usageStatisticsEnabled": false
-  }
-}
-```
-
-This configuration:
-
-- Forces all tool execution into a Docker sandbox.
-- Strictly uses an allowlist for a small set of safe shell commands and file
-  tools.
-- Defines and allows a single corporate MCP server for custom tools.
-- Enables telemetry for auditing, without logging prompt content.
-- Redirects the `/bug` command to an internal ticketing system.
-- Disables general usage statistics collection.

package/dist/docs/cli/gemini-ignore.md

@@ -1,71 +0,0 @@
-# Ignoring files
-
-This document provides an overview of the Gemini Ignore (`.geminiignore`)
-feature of the Gemini CLI.
-
-The Gemini CLI includes the ability to automatically ignore files, similar to
-`.gitignore` (used by Git) and `.aiexclude` (used by Gemini Code Assist). Adding
-paths to your `.geminiignore` file will exclude them from tools that support
-this feature, although they will still be visible to other services (such as
-Git).
-
-## How it works
-
-When you add a path to your `.geminiignore` file, tools that respect this file
-will exclude matching files and directories from their operations. For example,
-when you use the `@` command to share files, any paths in your `.geminiignore`
-file will be automatically excluded.
-
-For the most part, `.geminiignore` follows the conventions of `.gitignore`
-files:
-
-- Blank lines and lines starting with `#` are ignored.
-- Standard glob patterns are supported (such as `*`, `?`, and `[]`).
-- Putting a `/` at the end will only match directories.
-- Putting a `/` at the beginning anchors the path relative to the
-  `.geminiignore` file.
-- `!` negates a pattern.
-
-You can update your `.geminiignore` file at any time. To apply the changes, you
-must restart your Gemini CLI session.
-
-## How to use `.geminiignore`
-
-To enable `.geminiignore`:
-
-1. Create a file named `.geminiignore` in the root of your project directory.
-
-To add a file or directory to `.geminiignore`:
-
-1. Open your `.geminiignore` file.
-2. Add the path or file you want to ignore, for example: `/archive/` or
-   `apikeys.txt`.
-
-### `.geminiignore` examples
-
-You can use `.geminiignore` to ignore directories and files:
-
-```
-# Exclude your /packages/ directory and all subdirectories
-/packages/
-
-# Exclude your apikeys.txt file
-apikeys.txt
-```
-
-You can use wildcards in your `.geminiignore` file with `*`:
-
-```
-# Exclude all .md files
-*.md
-```
-
-Finally, you can exclude files and directories from exclusion with `!`:
-
-```
-# Exclude all .md files except README.md
-*.md
-!README.md
-```
-
-To remove paths from your `.geminiignore` file, delete the relevant lines.