@office-ai/aioncli-core 0.30.0 → 0.30.1

package/dist/docs/reference/policy-engine.md

@@ -0,0 +1,386 @@
+# Policy engine
+
+The Gemini CLI includes a powerful policy engine that provides fine-grained
+control over tool execution. It allows users and administrators to define rules
+that determine whether a tool call should be allowed, denied, or require user
+confirmation.
+
+## Quick start
+
+To create your first policy:
+
+1.  **Create the policy directory** if it doesn't exist:
+
+    **macOS/Linux**
+
+    ```bash
+    mkdir -p ~/.gemini/policies
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini\policies"
+    ```
+
+2.  **Create a new policy file** (e.g., `~/.gemini/policies/my-rules.toml`). You
+    can use any filename ending in `.toml`; all such files in this directory
+    will be loaded and combined:
+    ```toml
+    [[rule]]
+    toolName = "run_shell_command"
+    commandPrefix = "git status"
+    decision = "allow"
+    priority = 100
+    ```
+3.  **Run a command** that triggers the policy (e.g., ask Gemini CLI to
+    `git status`). The tool will now execute automatically without prompting for
+    confirmation.
+
+## Core concepts
+
+The policy engine operates on a set of rules. Each rule is a combination of
+conditions and a resulting decision. When a large language model wants to
+execute a tool, the policy engine evaluates all rules to find the
+highest-priority rule that matches the tool call.
+
+A rule consists of the following main components:
+
+- **Conditions**: Criteria that a tool call must meet for the rule to apply.
+  This can include the tool's name, the arguments provided to it, or the current
+  approval mode.
+- **Decision**: The action to take if the rule matches (`allow`, `deny`, or
+  `ask_user`).
+- **Priority**: A number that determines the rule's precedence. Higher numbers
+  win.
+
+For example, this rule will ask for user confirmation before executing any `git`
+command.
+
+```toml
+[[rule]]
+toolName = "run_shell_command"
+commandPrefix = "git "
+decision = "ask_user"
+priority = 100
+```
+
+### Conditions
+
+Conditions are the criteria that a tool call must meet for a rule to apply. The
+primary conditions are the tool's name and its arguments.
+
+#### Tool Name
+
+The `toolName` in the rule must match the name of the tool being called.
+
+- **Wildcards**: You can use wildcards to match multiple tools.
+  - `*`: Matches **any tool** (built-in or MCP).
+  - `mcp_server_*`: Matches any tool from a specific MCP server.
+  - `mcp_*_toolName`: Matches a specific tool name across **all** MCP servers.
+  - `mcp_*`: Matches **any tool from any MCP server**.
+
+> **Recommendation:** While FQN wildcards are supported, the recommended
+> approach for MCP tools is to use the `mcpName` field in your TOML rules. See
+> [Special syntax for MCP tools](#special-syntax-for-mcp-tools).
+
+#### Arguments pattern
+
+If `argsPattern` is specified, the tool's arguments are converted to a stable
+JSON string, which is then tested against the provided regular expression. If
+the arguments don't match the pattern, the rule does not apply.
+
+### Decisions
+
+There are three possible decisions a rule can enforce:
+
+- `allow`: The tool call is executed automatically without user interaction.
+- `deny`: The tool call is blocked and is not executed. For global rules (those
+  without an `argsPattern`), tools that are denied are **completely excluded
+  from the model's memory**. This means the model will not even see the tool as
+  an option, which is more secure and saves context window space.
+- `ask_user`: The user is prompted to approve or deny the tool call. (In
+  non-interactive mode, this is treated as `deny`.)
+
+> **Note:** The `deny` decision is the recommended way to exclude tools. The
+> legacy `tools.exclude` setting in `settings.json` is deprecated in favor of
+> policy rules with a `deny` decision.
+
+### Priority system and tiers
+
+The policy engine uses a sophisticated priority system to resolve conflicts when
+multiple rules match a single tool call. The core principle is simple: **the
+rule with the highest priority wins**.
+
+To provide a clear hierarchy, policies are organized into three tiers. Each tier
+has a designated number that forms the base of the final priority calculation.
+
+| Tier      | Base | Description                                                                |
+| :-------- | :--- | :------------------------------------------------------------------------- |
+| Default   | 1    | Built-in policies that ship with the Gemini CLI.                           |
+| Extension | 2    | Policies defined in extensions.                                            |
+| Workspace | 3    | Policies defined in the current workspace's configuration directory.       |
+| User      | 4    | Custom policies defined by the user.                                       |
+| Admin     | 5    | Policies managed by an administrator (e.g., in an enterprise environment). |
+
+Within a TOML policy file, you assign a priority value from **0 to 999**. The
+engine transforms this into a final priority using the following formula:
+
+`final_priority = tier_base + (toml_priority / 1000)`
+
+This system guarantees that:
+
+- Admin policies always override User, Workspace, and Default policies.
+- User policies override Workspace and Default policies.
+- Workspace policies override Default policies.
+- You can still order rules within a single tier with fine-grained control.
+
+For example:
+
+- A `priority: 50` rule in a Default policy file becomes `1.050`.
+- A `priority: 10` rule in a Workspace policy policy file becomes `2.010`.
+- A `priority: 100` rule in a User policy file becomes `3.100`.
+- A `priority: 20` rule in an Admin policy file becomes `4.020`.
+
+### Approval modes
+
+Approval modes allow the policy engine to apply different sets of rules based on
+the CLI's operational mode. A rule can be associated with one or more modes
+(e.g., `yolo`, `autoEdit`, `plan`). The rule will only be active if the CLI is
+running in one of its specified modes. If a rule has no modes specified, it is
+always active.
+
+- `default`: The standard interactive mode where most write tools require
+  confirmation.
+- `autoEdit`: Optimized for automated code editing; some write tools may be
+  auto-approved.
+- `plan`: A strict, read-only mode for research and design. See
+  [Customizing Plan Mode Policies](../cli/plan-mode.md#customizing-policies).
+- `yolo`: A mode where all tools are auto-approved (use with extreme caution).
+
+## Rule matching
+
+When a tool call is made, the engine checks it against all active rules,
+starting from the highest priority. The first rule that matches determines the
+outcome.
+
+A rule matches a tool call if all of its conditions are met:
+
+1.  **Tool name**: The `toolName` in the rule must match the name of the tool
+    being called.
+    - **Wildcards**: You can use wildcards like `*`, `mcp_server_*`, or
+      `mcp_*_toolName` to match multiple tools. See [Tool Name](#tool-name) for
+      details.
+2.  **Arguments pattern**: If `argsPattern` is specified, the tool's arguments
+    are converted to a stable JSON string, which is then tested against the
+    provided regular expression. If the arguments don't match the pattern, the
+    rule does not apply.
+
+## Configuration
+
+Policies are defined in `.toml` files. The CLI loads these files from Default,
+User, and (if configured) Admin directories.
+
+### Policy locations
+
+| Tier          | Type   | Location                                  |
+| :------------ | :----- | :---------------------------------------- |
+| **User**      | Custom | `~/.gemini/policies/*.toml`               |
+| **Workspace** | Custom | `$WORKSPACE_ROOT/.gemini/policies/*.toml` |
+| **Admin**     | System | _See below (OS specific)_                 |
+
+#### System-wide policies (Admin)
+
+Administrators can enforce system-wide policies (Tier 3) that override all user
+and default settings. These policies must be placed in specific, secure
+directories:
+
+| OS          | Policy Directory Path                             |
+| :---------- | :------------------------------------------------ |
+| **Linux**   | `/etc/gemini-cli/policies`                        |
+| **macOS**   | `/Library/Application Support/GeminiCli/policies` |
+| **Windows** | `C:\ProgramData\gemini-cli\policies`              |
+
+**Security Requirements:**
+
+To prevent privilege escalation, the CLI enforces strict security checks on
+admin directories. If checks fail, system policies are **ignored**.
+
+- **Linux / macOS:** Must be owned by `root` (UID 0) and NOT writable by group
+  or others (e.g., `chmod 755`).
+- **Windows:** Must be in `C:\ProgramData`. Standard users (`Users`, `Everyone`)
+  must NOT have `Write`, `Modify`, or `Full Control` permissions. _Tip: If you
+  see a security warning, use the folder properties to remove write permissions
+  for non-admin groups. You may need to "Disable inheritance" in Advanced
+  Security Settings._
+
+### TOML rule schema
+
+Here is a breakdown of the fields available in a TOML policy rule:
+
+```toml
+[[rule]]
+# A unique name for the tool, or an array of names.
+toolName = "run_shell_command"
+
+# (Optional) The name of a subagent. If provided, the rule only applies to tool calls
+# made by this specific subagent.
+subagent = "generalist"
+
+# (Optional) The name of an MCP server. Can be combined with toolName
+# to form a composite FQN internally like "mcp_mcpName_toolName".
+mcpName = "my-custom-server"
+
+# (Optional) Metadata hints provided by the tool. A rule matches if all
+# key-value pairs provided here are present in the tool's annotations.
+toolAnnotations = { readOnlyHint = true }
+
+# (Optional) A regex to match against the tool's arguments.
+argsPattern = '"command":"(git|npm)'
+
+# (Optional) A string or array of strings that a shell command must start with.
+# This is syntactic sugar for `toolName = "run_shell_command"` and an `argsPattern`.
+commandPrefix = "git "
+
+# (Optional) A regex to match against the entire shell command.
+# This is also syntactic sugar for `toolName = "run_shell_command"`.
+# Note: This pattern is tested against the JSON representation of the arguments (e.g., `{"command":"<your_command>"}`).
+# Because it prepends `"command":"`, it effectively matches from the start of the command.
+# Anchors like `^` or `$` apply to the full JSON string, so `^` should usually be avoided here.
+# You cannot use commandPrefix and commandRegex in the same rule.
+commandRegex = "git (commit|push)"
+
+# The decision to take. Must be "allow", "deny", or "ask_user".
+decision = "ask_user"
+
+# The priority of the rule, from 0 to 999.
+priority = 10
+
+# (Optional) A custom message to display when a tool call is denied by this rule.
+# This message is returned to the model and user, useful for explaining *why* it was denied.
+deny_message = "Deletion is permanent"
+
+# (Optional) An array of approval modes where this rule is active.
+modes = ["autoEdit"]
+```
+
+### Using arrays (lists)
+
+To apply the same rule to multiple tools or command prefixes, you can provide an
+array of strings for the `toolName` and `commandPrefix` fields.
+
+**Example:**
+
+This single rule will apply to both the `write_file` and `replace` tools.
+
+```toml
+[[rule]]
+toolName = ["write_file", "replace"]
+decision = "ask_user"
+priority = 10
+```
+
+### Special syntax for `run_shell_command`
+
+To simplify writing policies for `run_shell_command`, you can use
+`commandPrefix` or `commandRegex` instead of the more complex `argsPattern`.
+
+- `commandPrefix`: Matches if the `command` argument starts with the given
+  string.
+- `commandRegex`: Matches if the `command` argument matches the given regular
+  expression.
+
+**Example:**
+
+This rule will ask for user confirmation before executing any `git` command.
+
+```toml
+[[rule]]
+toolName = "run_shell_command"
+commandPrefix = "git "
+decision = "ask_user"
+priority = 100
+```
+
+### Special syntax for MCP tools
+
+You can create rules that target tools from Model Context Protocol (MCP) servers
+using the `mcpName` field. **This is the recommended approach** for defining MCP
+policies, as it is much more robust than manually writing Fully Qualified Names
+(FQNs) or string wildcards.
+
+> **Warning:** Do not use underscores (`_`) in your MCP server names (e.g., use
+> `my-server` rather than `my_server`). The policy parser splits Fully Qualified
+> Names (`mcp_server_tool`) on the _first_ underscore following the `mcp_`
+> prefix. If your server name contains an underscore, the parser will
+> misinterpret the server identity, which can cause wildcard rules and security
+> policies to fail silently.
+
+**1. Targeting a specific tool on a server**
+
+Combine `mcpName` and `toolName` to target a single operation.
+
+```toml
+# Allows the `search` tool on the `my-jira-server` MCP
+[[rule]]
+mcpName = "my-jira-server"
+toolName = "search"
+decision = "allow"
+priority = 200
+```
+
+**2. Targeting all tools on a specific server**
+
+Specify only the `mcpName` to apply a rule to every tool provided by that
+server.
+
+```toml
+# Denies all tools from the `untrusted-server` MCP
+[[rule]]
+mcpName = "untrusted-server"
+decision = "deny"
+priority = 500
+deny_message = "This server is not trusted by the admin."
+```
+
+**3. Targeting all MCP servers**
+
+Use `mcpName = "*"` to create a rule that applies to **all** tools from **any**
+registered MCP server. This is useful for setting category-wide defaults.
+
+```toml
+# Ask user for any tool call from any MCP server
+[[rule]]
+mcpName = "*"
+decision = "ask_user"
+priority = 10
+```
+
+**4. Targeting a tool name across all servers**
+
+Use `mcpName = "*"` with a specific `toolName` to target that operation
+regardless of which server provides it.
+
+```toml
+# Allow the `search` tool across all connected MCP servers
+[[rule]]
+mcpName = "*"
+toolName = "search"
+decision = "allow"
+priority = 50
+```
+
+## Default policies
+
+The Gemini CLI ships with a set of default policies to provide a safe
+out-of-the-box experience.
+
+- **Read-only tools** (like `read_file`, `glob`) are generally **allowed**.
+- **Agent delegation** defaults to **`ask_user`** to ensure remote agents can
+  prompt for confirmation, but local sub-agent actions are executed silently and
+  checked individually.
+- **Write tools** (like `write_file`, `run_shell_command`) default to
+  **`ask_user`**.
+- In **`yolo`** mode, a high-priority rule allows all tools.
+- In **`autoEdit`** mode, rules allow certain write operations to happen without
+  prompting.

package/dist/docs/reference/tools.md

@@ -0,0 +1,106 @@
+# Tools reference
+
+Gemini CLI uses tools to interact with your local environment, access
+information, and perform actions on your behalf. These tools extend the model's
+capabilities beyond text generation, letting it read files, execute commands,
+and search the web.
+
+## How to use Gemini CLI's tools
+
+Tools are generally invoked automatically by Gemini CLI when it needs to perform
+an action. However, you can also trigger specific tools manually using shorthand
+syntax.
+
+### Automatic execution and security
+
+When the model wants to use a tool, Gemini CLI evaluates the request against its
+security policies.
+
+- **User confirmation:** You must manually approve tools that modify files or
+  execute shell commands (mutators). The CLI shows you a diff or the exact
+  command before you confirm.
+- **Sandboxing:** You can run tool executions in secure, containerized
+  environments to isolate changes from your host system. For more details, see
+  the [Sandboxing](../cli/sandbox.md) guide.
+- **Trusted folders:** You can configure which directories allow the model to
+  use system tools. For more details, see the
+  [Trusted folders](../cli/trusted-folders.md) guide.
+
+Review confirmation prompts carefully before allowing a tool to execute.
+
+### How to use manually-triggered tools
+
+You can directly trigger key tools using special syntax in your prompt:
+
+- **[File access](../tools/file-system.md#read_many_files) (`@`):** Use the `@`
+  symbol followed by a file or directory path to include its content in your
+  prompt. This triggers the `read_many_files` tool.
+- **[Shell commands](../tools/shell.md) (`!`):** Use the `!` symbol followed by
+  a system command to execute it directly. This triggers the `run_shell_command`
+  tool.
+
+## How to manage tools
+
+Using built-in commands, you can inspect available tools and configure how they
+behave.
+
+### Tool discovery
+
+Use the `/tools` command to see what tools are currently active in your session.
+
+- **`/tools`**: Lists all registered tools with their display names.
+- **`/tools desc`**: Lists all tools with their full descriptions.
+
+This is especially useful for verifying that
+[MCP servers](../tools/mcp-server.md) or custom tools are loaded correctly.
+
+### Tool configuration
+
+You can enable, disable, or configure specific tools in your settings. For
+example, you can set a specific pager for shell commands or configure the
+browser used for web searches. See the [Settings](../cli/settings.md) guide for
+details.
+
+## Available tools
+
+The following table lists all available tools, categorized by their primary
+function.
+
+| Category    | Tool                                             | Kind          | Description                                                                                                                                                                                                                                 |
+| :---------- | :----------------------------------------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Execution   | [`run_shell_command`](../tools/shell.md)         | `Execute`     | Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation.<br><br>**Parameters:** `command`, `description`, `dir_path`, `is_background`                                       |
+| File System | [`glob`](../tools/file-system.md)                | `Search`      | Finds files matching specific glob patterns across the workspace.<br><br>**Parameters:** `pattern`, `dir_path`, `case_sensitive`, `respect_git_ignore`, `respect_gemini_ignore`                                                             |
+| File System | [`grep_search`](../tools/file-system.md)         | `Search`      | Searches for a regular expression pattern within file contents. Legacy alias: `search_file_content`.<br><br>**Parameters:** `pattern`, `dir_path`, `include`, `exclude_pattern`, `names_only`, `max_matches_per_file`, `total_max_matches`  |
+| File System | [`list_directory`](../tools/file-system.md)      | `Read`        | Lists the names of files and subdirectories within a specified path.<br><br>**Parameters:** `dir_path`, `ignore`, `file_filtering_options`                                                                                                  |
+| File System | [`read_file`](../tools/file-system.md)           | `Read`        | Reads the content of a specific file. Supports text, images, audio, and PDF.<br><br>**Parameters:** `file_path`, `start_line`, `end_line`                                                                                                   |
+| File System | [`read_many_files`](../tools/file-system.md)     | `Read`        | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt.<br><br>**Parameters:** `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options`                              |
+| File System | [`replace`](../tools/file-system.md)             | `Edit`        | Performs precise text replacement within a file. Requires manual confirmation.<br><br>**Parameters:** `file_path`, `instruction`, `old_string`, `new_string`, `allow_multiple`                                                              |
+| File System | [`write_file`](../tools/file-system.md)          | `Edit`        | Creates or overwrites a file with new content. Requires manual confirmation.<br><br>**Parameters:** `file_path`, `content`                                                                                                                  |
+| Interaction | [`ask_user`](../tools/ask-user.md)               | `Communicate` | Requests clarification or missing information via an interactive dialog.<br><br>**Parameters:** `questions`                                                                                                                                 |
+| Interaction | [`write_todos`](../tools/todos.md)               | `Other`       | Maintains an internal list of subtasks. The model uses this to track its own progress and display it to you.<br><br>**Parameters:** `todos`                                                                                                 |
+| Memory      | [`activate_skill`](../tools/activate-skill.md)   | `Other`       | Loads specialized procedural expertise for specific tasks from the `.gemini/skills` directory.<br><br>**Parameters:** `name`                                                                                                                |
+| Memory      | [`get_internal_docs`](../tools/internal-docs.md) | `Think`       | Accesses Gemini CLI's own documentation to provide more accurate answers about its capabilities.<br><br>**Parameters:** `path`                                                                                                              |
+| Memory      | [`save_memory`](../tools/memory.md)              | `Think`       | Persists specific facts and project details to your `GEMINI.md` file to retain context.<br><br>**Parameters:** `fact`                                                                                                                       |
+| Planning    | [`enter_plan_mode`](../tools/planning.md)        | `Plan`        | Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes.<br><br>**Parameters:** `reason`                                                                                                                          |
+| Planning    | [`exit_plan_mode`](../tools/planning.md)         | `Plan`        | Finalizes a plan, presents it for review, and requests approval to start implementation.<br><br>**Parameters:** `plan`                                                                                                                      |
+| System      | `complete_task`                                  | `Other`       | Finalizes a subagent's mission and returns the result to the parent agent. This tool is not available to the user.<br><br>**Parameters:** `result`                                                                                          |
+| Web         | [`google_web_search`](../tools/web-search.md)    | `Search`      | Performs a Google Search to find up-to-date information.<br><br>**Parameters:** `query`                                                                                                                                                     |
+| Web         | [`web_fetch`](../tools/web-fetch.md)             | `Fetch`       | Retrieves and processes content from specific URLs. **Warning:** This tool can access local and private network addresses (e.g., localhost), which may pose a security risk if used with untrusted prompts.<br><br>**Parameters:** `prompt` |
+
+## Under the hood
+
+For developers, the tool system is designed to be extensible and robust. The
+`ToolRegistry` class manages all available tools.
+
+You can extend Gemini CLI with custom tools by configuring
+`tools.discoveryCommand` in your settings or by connecting to MCP servers.
+
+> **Note:** For a deep dive into the internal Tool API and how to implement your
+> own tools in the codebase, see the `packages/core/src/tools/` directory in
+> GitHub.
+
+## Next steps
+
+- Learn how to [Set up an MCP server](../tools/mcp-server.md).
+- Explore [Agent Skills](../cli/skills.md) for specialized expertise.
+- See the [Command reference](./commands.md) for slash commands.

package/dist/docs/resources/faq.md

@@ -0,0 +1,175 @@
+# Frequently asked questions (FAQ)
+
+This page provides answers to common questions and solutions to frequent
+problems encountered while using Gemini CLI.
+
+## General issues
+
+This section addresses common questions about Gemini CLI usage, security, and
+troubleshooting general errors.
+
+### Why can't I use third-party software (e.g. Claude Code, OpenClaw, OpenCode) with Gemini CLI?
+
+Using third-party software, tools, or services to harvest or piggyback on Gemini
+CLI's OAuth authentication to access our backend services is a direct violation
+of our [applicable terms and policies](tos-privacy.md). Doing so bypasses our
+intended authentication and security structures, and such actions may be grounds
+for immediate suspension or termination of your account. If you would like to
+use a third-party coding agent with Gemini, the supported and secure method is
+to use a Vertex AI or Google AI Studio API key.
+
+### Why am I getting an `API error: 429 - Resource exhausted`?
+
+This error indicates that you have exceeded your API request limit. The Gemini
+API has rate limits to prevent abuse and ensure fair usage.
+
+To resolve this, you can:
+
+- **Check your usage:** Review your API usage in the Google AI Studio or your
+  Google Cloud project dashboard.
+- **Optimize your prompts:** If you are making many requests in a short period,
+  try to batch your prompts or introduce delays between requests.
+- **Request a quota increase:** If you consistently need a higher limit, you can
+  request a quota increase from Google.
+
+### Why am I getting an `ERR_REQUIRE_ESM` error when running `npm run start`?
+
+This error typically occurs in Node.js projects when there is a mismatch between
+CommonJS and ES Modules.
+
+This is often due to a misconfiguration in your `package.json` or
+`tsconfig.json`. Ensure that:
+
+1.  Your `package.json` has `"type": "module"`.
+2.  Your `tsconfig.json` has `"module": "NodeNext"` or a compatible setting in
+    the `compilerOptions`.
+
+If the problem persists, try deleting your `node_modules` directory and
+`package-lock.json` file, and then run `npm install` again.
+
+### Why don't I see cached token counts in my stats output?
+
+Cached token information is only displayed when cached tokens are being used.
+This feature is available for API key users (Gemini API key or Google Cloud
+Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts
+like Google Gmail or Google Workspace, respectively). This is because the Gemini
+Code Assist API does not support cached content creation. You can still view
+your total token usage using the `/stats` command in Gemini CLI.
+
+## Installation and updates
+
+### How do I update Gemini CLI to the latest version?
+
+If you installed it globally via `npm`, update it using the command
+`npm install -g @google/gemini-cli@latest`. If you compiled it from source, pull
+the latest changes from the repository, and then rebuild using the command
+`npm run build`.
+
+## Platform-specific issues
+
+### Why does the CLI crash on Windows when I run a command like `chmod +x`?
+
+Commands like `chmod` are specific to Unix-like operating systems (Linux,
+macOS). They are not available on Windows by default.
+
+To resolve this, you can:
+
+- **Use Windows-equivalent commands:** Instead of `chmod`, you can use `icacls`
+  to modify file permissions on Windows.
+- **Use a compatibility layer:** Tools like Git Bash or Windows Subsystem for
+  Linux (WSL) provide a Unix-like environment on Windows where these commands
+  will work.
+
+## Configuration
+
+### How do I configure my `GOOGLE_CLOUD_PROJECT`?
+
+You can configure your Google Cloud Project ID using an environment variable.
+
+Set the `GOOGLE_CLOUD_PROJECT` environment variable in your shell:
+
+**macOS/Linux**
+
+```bash
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+```
+
+**Windows (PowerShell)**
+
+```powershell
+$env:GOOGLE_CLOUD_PROJECT="your-project-id"
+```
+
+To make this setting permanent, add this line to your shell's startup file
+(e.g., `~/.bashrc`, `~/.zshrc`).
+
+### What is the best way to store my API keys securely?
+
+Exposing API keys in scripts or checking them into source control is a security
+risk.
+
+To store your API keys securely, you can:
+
+- **Use a `.env` file:** Create a `.env` file in your project's `.gemini`
+  directory (`.gemini/.env`) and store your keys there. Gemini CLI will
+  automatically load these variables.
+- **Use your system's keyring:** For the most secure storage, use your operating
+  system's secret management tool (like macOS Keychain, Windows Credential
+  Manager, or a secret manager on Linux). You can then have your scripts or
+  environment load the key from the secure storage at runtime.
+
+### Where are the Gemini CLI configuration and settings files stored?
+
+The Gemini CLI configuration is stored in two `settings.json` files:
+
+1.  In your home directory: `~/.gemini/settings.json`.
+2.  In your project's root directory: `./.gemini/settings.json`.
+
+Refer to [Gemini CLI Configuration](../reference/configuration.md) for more
+details.
+
+## Google AI Pro/Ultra and subscription FAQs
+
+### Where can I learn more about my Google AI Pro or Google AI Ultra subscription?
+
+To learn more about your Google AI Pro or Google AI Ultra subscription, visit
+**Manage subscription** in your [subscription settings](https://one.google.com).
+
+### How do I know if I have higher limits for Google AI Pro or Ultra?
+
+If you're subscribed to Google AI Pro or Ultra, you automatically have higher
+limits to Gemini Code Assist and Gemini CLI. These are shared across Gemini CLI
+and agent mode in the IDE. You can confirm you have higher limits by checking if
+you are still subscribed to Google AI Pro or Ultra in your
+[subscription settings](https://one.google.com).
+
+### What is the privacy policy for using Gemini Code Assist or Gemini CLI if I've subscribed to Google AI Pro or Ultra?
+
+To learn more about your privacy policy and terms of service governed by your
+subscription, visit
+[Gemini Code Assist: Terms of Service and Privacy Policies](https://developers.google.com/gemini-code-assist/resources/privacy-notices).
+
+### I've upgraded to Google AI Pro or Ultra but it still says I am hitting quota limits. Is this a bug?
+
+The higher limits in your Google AI Pro or Ultra subscription are for Gemini 2.5
+across both Gemini 2.5 Pro and Flash. They are shared quota across Gemini CLI
+and agent mode in Gemini Code Assist IDE extensions. You can learn more about
+quota limits for Gemini CLI, Gemini Code Assist and agent mode in Gemini Code
+Assist at
+[Quotas and limits](https://developers.google.com/gemini-code-assist/resources/quotas).
+
+### If I upgrade to higher limits for Gemini CLI and Gemini Code Assist by purchasing a Google AI Pro or Ultra subscription, will Gemini start using my data to improve its machine learning models?
+
+Google does not use your data to improve Google's machine learning models if you
+purchase a paid plan. Note: If you decide to remain on the free version of
+Gemini Code Assist, Gemini Code Assist for individuals, you can also opt out of
+using your data to improve Google's machine learning models. See the
+[Gemini Code Assist for individuals privacy notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals)
+for more information.
+
+## Not seeing your question?
+
+Search the
+[Gemini CLI Q&A discussions on GitHub](https://github.com/google-gemini/gemini-cli/discussions/categories/q-a)
+or
+[start a new discussion on GitHub](https://github.com/google-gemini/gemini-cli/discussions/new?category=q-a)