@office-ai/aioncli-core 0.18.7 → 0.24.0

package/dist/docs/extensions/getting-started-extensions.md

@@ -0,0 +1,245 @@
+# Getting started with Gemini CLI extensions
+
+This guide will walk you through creating your first Gemini CLI extension.
+You'll learn how to set up a new extension, add a custom tool via an MCP server,
+create a custom command, and provide context to the model with a `GEMINI.md`
+file.
+
+## Prerequisites
+
+Before you start, make sure you have the Gemini CLI installed and a basic
+understanding of Node.js and TypeScript.
+
+## Step 1: Create a new extension
+
+The easiest way to start is by using one of the built-in templates. We'll use
+the `mcp-server` example as our foundation.
+
+Run the following command to create a new directory called `my-first-extension`
+with the template files:
+
+```bash
+gemini extensions new my-first-extension mcp-server
+```
+
+This will create a new directory with the following structure:
+
+```
+my-first-extension/
+├── example.ts
+├── gemini-extension.json
+├── package.json
+└── tsconfig.json
+```
+
+## Step 2: Understand the extension files
+
+Let's look at the key files in your new extension.
+
+### `gemini-extension.json`
+
+This is the manifest file for your extension. It tells Gemini CLI how to load
+and use your extension.
+
+```json
+{
+  "name": "my-first-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "nodeServer": {
+      "command": "node",
+      "args": ["${extensionPath}${/}dist${/}example.js"],
+      "cwd": "${extensionPath}"
+    }
+  }
+}
+```
+
+- `name`: The unique name for your extension.
+- `version`: The version of your extension.
+- `mcpServers`: This section defines one or more Model Context Protocol (MCP)
+  servers. MCP servers are how you can add new tools for the model to use.
+  - `command`, `args`, `cwd`: These fields specify how to start your server.
+    Notice the use of the `${extensionPath}` variable, which Gemini CLI replaces
+    with the absolute path to your extension's installation directory. This
+    allows your extension to work regardless of where it's installed.
+
+### `example.ts`
+
+This file contains the source code for your MCP server. It's a simple Node.js
+server that uses the `@modelcontextprotocol/sdk`.
+
+```typescript
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({
+  name: 'prompt-server',
+  version: '1.0.0',
+});
+
+// Registers a new tool named 'fetch_posts'
+server.registerTool(
+  'fetch_posts',
+  {
+    description: 'Fetches a list of posts from a public API.',
+    inputSchema: z.object({}).shape,
+  },
+  async () => {
+    const apiResponse = await fetch(
+      'https://jsonplaceholder.typicode.com/posts',
+    );
+    const posts = await apiResponse.json();
+    const response = { posts: posts.slice(0, 5) };
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response),
+        },
+      ],
+    };
+  },
+);
+
+// ... (prompt registration omitted for brevity)
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+This server defines a single tool called `fetch_posts` that fetches data from a
+public API.
+
+### `package.json` and `tsconfig.json`
+
+These are standard configuration files for a TypeScript project. The
+`package.json` file defines dependencies and a `build` script, and
+`tsconfig.json` configures the TypeScript compiler.
+
+## Step 3: Build and link your extension
+
+Before you can use the extension, you need to compile the TypeScript code and
+link the extension to your Gemini CLI installation for local development.
+
+1.  **Install dependencies:**
+
+    ```bash
+    cd my-first-extension
+    npm install
+    ```
+
+2.  **Build the server:**
+
+    ```bash
+    npm run build
+    ```
+
+    This will compile `example.ts` into `dist/example.js`, which is the file
+    referenced in your `gemini-extension.json`.
+
+3.  **Link the extension:**
+
+    The `link` command creates a symbolic link from the Gemini CLI extensions
+    directory to your development directory. This means any changes you make
+    will be reflected immediately without needing to reinstall.
+
+    ```bash
+    gemini extensions link .
+    ```
+
+Now, restart your Gemini CLI session. The new `fetch_posts` tool will be
+available. You can test it by asking: "fetch posts".
+
+## Step 4: Add a custom command
+
+Custom commands provide a way to create shortcuts for complex prompts. Let's add
+a command that searches for a pattern in your code.
+
+1.  Create a `commands` directory and a subdirectory for your command group:
+
+    ```bash
+    mkdir -p commands/fs
+    ```
+
+2.  Create a file named `commands/fs/grep-code.toml`:
+
+    ```toml
+    prompt = """
+    Please summarize the findings for the pattern `{{args}}`.
+
+    Search Results:
+    !{grep -r {{args}} .}
+    """
+    ```
+
+    This command, `/fs:grep-code`, will take an argument, run the `grep` shell
+    command with it, and pipe the results into a prompt for summarization.
+
+After saving the file, restart the Gemini CLI. You can now run
+`/fs:grep-code "some pattern"` to use your new command.
+
+## Step 5: Add a custom `GEMINI.md`
+
+You can provide persistent context to the model by adding a `GEMINI.md` file to
+your extension. This is useful for giving the model instructions on how to
+behave or information about your extension's tools. Note that you may not always
+need this for extensions built to expose commands and prompts.
+
+1.  Create a file named `GEMINI.md` in the root of your extension directory:
+
+    ```markdown
+    # My First Extension Instructions
+
+    You are an expert developer assistant. When the user asks you to fetch
+    posts, use the `fetch_posts` tool. Be concise in your responses.
+    ```
+
+2.  Update your `gemini-extension.json` to tell the CLI to load this file:
+
+    ```json
+    {
+      "name": "my-first-extension",
+      "version": "1.0.0",
+      "contextFileName": "GEMINI.md",
+      "mcpServers": {
+        "nodeServer": {
+          "command": "node",
+          "args": ["${extensionPath}${/}dist${/}example.js"],
+          "cwd": "${extensionPath}"
+        }
+      }
+    }
+    ```
+
+Restart the CLI again. The model will now have the context from your `GEMINI.md`
+file in every session where the extension is active.
+
+## Step 6: Releasing your extension
+
+Once you are happy with your extension, you can share it with others. The two
+primary ways of releasing extensions are via a Git repository or through GitHub
+Releases. Using a public Git repository is the simplest method.
+
+For detailed instructions on both methods, please refer to the
+[Extension Releasing Guide](./extension-releasing.md).
+
+## Conclusion
+
+You've successfully created a Gemini CLI extension! You learned how to:
+
+- Bootstrap a new extension from a template.
+- Add custom tools with an MCP server.
+- Create convenient custom commands.
+- Provide persistent context to the model.
+- Link your extension for local development.
+
+From here, you can explore more advanced features and build powerful new
+capabilities into the Gemini CLI.

package/dist/docs/extensions/index.md

@@ -0,0 +1,293 @@
+# Gemini CLI extensions
+
+_This documentation is up-to-date with the v0.4.0 release._
+
+Gemini CLI extensions package prompts, MCP servers, and custom commands into a
+familiar and user-friendly format. With extensions, you can expand the
+capabilities of Gemini CLI and share those capabilities with others. They are
+designed to be easily installable and shareable.
+
+To see examples of extensions, you can browse a gallery of
+[Gemini CLI extensions](https://geminicli.com/extensions/browse/).
+
+See [getting started docs](getting-started-extensions.md) for a guide on
+creating your first extension.
+
+See [releasing docs](extension-releasing.md) for an advanced guide on setting up
+GitHub releases.
+
+## Extension management
+
+We offer a suite of extension management tools using `gemini extensions`
+commands.
+
+Note that these commands are not supported from within the CLI, although you can
+list installed extensions using the `/extensions list` subcommand.
+
+Note that all of these commands will only be reflected in active CLI sessions on
+restart.
+
+### Installing an extension
+
+You can install an extension using `gemini extensions install` with either a
+GitHub URL or a local path.
+
+Note that we create a copy of the installed extension, so you will need to run
+`gemini extensions update` to pull in changes from both locally-defined
+extensions and those on GitHub.
+
+NOTE: If you are installing an extension from GitHub, you'll need to have `git`
+installed on your machine. See
+[git installation instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+for help.
+
+```
+gemini extensions install <source> [--ref <ref>] [--auto-update] [--pre-release] [--consent]
+```
+
+- `<source>`: The github URL or local path of the extension to install.
+- `--ref`: The git ref to install from.
+- `--auto-update`: Enable auto-update for this extension.
+- `--pre-release`: Enable pre-release versions for this extension.
+- `--consent`: Acknowledge the security risks of installing an extension and
+  skip the confirmation prompt.
+
+### Uninstalling an extension
+
+To uninstall one or more extensions, run
+`gemini extensions uninstall <name...>`:
+
+```
+gemini extensions uninstall gemini-cli-security gemini-cli-another-extension
+```
+
+### Disabling an extension
+
+Extensions are, by default, enabled across all workspaces. You can disable an
+extension entirely or for specific workspace.
+
+```
+gemini extensions disable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to disable.
+- `--scope`: The scope to disable the extension in (`user` or `workspace`).
+
+### Enabling an extension
+
+You can enable extensions using `gemini extensions enable <name>`. You can also
+enable an extension for a specific workspace using
+`gemini extensions enable <name> --scope=workspace` from within that workspace.
+
+```
+gemini extensions enable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to enable.
+- `--scope`: The scope to enable the extension in (`user` or `workspace`).
+
+### Updating an extension
+
+For extensions installed from a local path or a git repository, you can
+explicitly update to the latest version (as reflected in the
+`gemini-extension.json` `version` field) with `gemini extensions update <name>`.
+
+You can update all extensions with:
+
+```
+gemini extensions update --all
+```
+
+### Create a boilerplate extension
+
+We offer several example extensions `context`, `custom-commands`,
+`exclude-tools` and `mcp-server`. You can view these examples
+[here](https://github.com/google-gemini/gemini-cli/tree/main/packages/cli/src/commands/extensions/examples).
+
+To copy one of these examples into a development directory using the type of
+your choosing, run:
+
+```
+gemini extensions new <path> [template]
+```
+
+- `<path>`: The path to create the extension in.
+- `[template]`: The boilerplate template to use.
+
+### Link a local extension
+
+The `gemini extensions link` command will create a symbolic link from the
+extension installation directory to the development path.
+
+This is useful so you don't have to run `gemini extensions update` every time
+you make changes you'd like to test.
+
+```
+gemini extensions link <path>
+```
+
+- `<path>`: The path of the extension to link.
+
+## How it works
+
+On startup, Gemini CLI looks for extensions in `<home>/.gemini/extensions`
+
+Extensions exist as a directory that contains a `gemini-extension.json` file.
+For example:
+
+`<home>/.gemini/extensions/my-extension/gemini-extension.json`
+
+### `gemini-extension.json`
+
+The `gemini-extension.json` file contains the configuration for the extension.
+The file has the following structure:
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "my-server": {
+      "command": "node my-server.js"
+    }
+  },
+  "contextFileName": "GEMINI.md",
+  "excludeTools": ["run_shell_command"]
+}
+```
+
+- `name`: The name of the extension. This is used to uniquely identify the
+  extension and for conflict resolution when extension commands have the same
+  name as user or project commands. The name should be lowercase or numbers and
+  use dashes instead of underscores or spaces. This is how users will refer to
+  your extension in the CLI. Note that we expect this name to match the
+  extension directory name.
+- `version`: The version of the extension.
+- `mcpServers`: A map of MCP servers to settings. The key is the name of the
+  server, and the value is the server configuration. These servers will be
+  loaded on startup just like MCP servers settingsd in a
+  [`settings.json` file](../get-started/configuration.md). If both an extension
+  and a `settings.json` file settings an MCP server with the same name, the
+  server defined in the `settings.json` file takes precedence.
+  - Note that all MCP server configuration options are supported except for
+    `trust`.
+- `contextFileName`: The name of the file that contains the context for the
+  extension. This will be used to load the context from the extension directory.
+  If this property is not used but a `GEMINI.md` file is present in your
+  extension directory, then that file will be loaded.
+- `excludeTools`: An array of tool names to exclude from the model. You can also
+  specify command-specific restrictions for tools that support it, like the
+  `run_shell_command` tool. For example,
+  `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf`
+  command. Note that this differs from the MCP server `excludeTools`
+  functionality, which can be listed in the MCP server config.
+
+When Gemini CLI starts, it loads all the extensions and merges their
+configurations. If there are any conflicts, the workspace configuration takes
+precedence.
+
+### Settings
+
+_Note: This is an experimental feature. We do not yet recommend extension
+authors introduce settings as part of their core flows._
+
+Extensions can define settings that the user will be prompted to provide upon
+installation. This is useful for things like API keys, URLs, or other
+configuration that the extension needs to function.
+
+To define settings, add a `settings` array to your `gemini-extension.json` file.
+Each object in the array should have the following properties:
+
+- `name`: A user-friendly name for the setting.
+- `description`: A description of the setting and what it's used for.
+- `envVar`: The name of the environment variable that the setting will be stored
+  as.
+- `sensitive`: Optional boolean. If true, obfuscates the input the user provides
+  and stores the secret in keychain storage. **Example**
+
+```json
+{
+  "name": "my-api-extension",
+  "version": "1.0.0",
+  "settings": [
+    {
+      "name": "API Key",
+      "description": "Your API key for the service.",
+      "envVar": "MY_API_KEY"
+    }
+  ]
+}
+```
+
+When a user installs this extension, they will be prompted to enter their API
+key. The value will be saved to a `.env` file in the extension's directory
+(e.g., `<home>/.gemini/extensions/my-api-extension/.env`).
+
+You can view a list of an extension's settings by running:
+
+```
+gemini extensions settings list <extension name>
+```
+
+and you can update a given setting using:
+
+```
+gemini extensions settings set <extension name> <setting name> [--scope <scope>]
+```
+
+- `--scope`: The scope to set the setting in (`user` or `workspace`). This is
+  optional and will default to `user`.
+
+### Custom commands
+
+Extensions can provide [custom commands](../cli/custom-commands.md) by placing
+TOML files in a `commands/` subdirectory within the extension directory. These
+commands follow the same format as user and project custom commands and use
+standard naming conventions.
+
+**Example**
+
+An extension named `gcp` with the following structure:
+
+```
+.gemini/extensions/gcp/
+├── gemini-extension.json
+└── commands/
+    ├── deploy.toml
+    └── gcs/
+        └── sync.toml
+```
+
+Would provide these commands:
+
+- `/deploy` - Shows as `[gcp] Custom command from deploy.toml` in help
+- `/gcs:sync` - Shows as `[gcp] Custom command from sync.toml` in help
+
+### Conflict resolution
+
+Extension commands have the lowest precedence. When a conflict occurs with user
+or project commands:
+
+1. **No conflict**: Extension command uses its natural name (e.g., `/deploy`)
+2. **With conflict**: Extension command is renamed with the extension prefix
+   (e.g., `/gcp.deploy`)
+
+For example, if both a user and the `gcp` extension define a `deploy` command:
+
+- `/deploy` - Executes the user's deploy command
+- `/gcp.deploy` - Executes the extension's deploy command (marked with `[gcp]`
+  tag)
+
+## Variables
+
+Gemini CLI extensions allow variable substitution in `gemini-extension.json`.
+This can be useful if e.g., you need the current directory to run an MCP server
+using `"cwd": "${extensionPath}${/}run.ts"`.
+
+**Supported variables:**
+
+| variable                   | description                                                                                                                                                     |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `${extensionPath}`         | The fully-qualified path of the extension in the user's filesystem e.g., '/Users/username/.gemini/extensions/example-extension'. This will not unwrap symlinks. |
+| `${workspacePath}`         | The fully-qualified path of the current workspace.                                                                                                              |
+| `${/} or ${pathSeparator}` | The path separator (differs per OS).                                                                                                                            |

package/dist/docs/faq.md

@@ -0,0 +1,154 @@
+# Frequently asked questions (FAQ)
+
+This page provides answers to common questions and solutions to frequent
+problems encountered while using Gemini CLI.
+
+## General issues
+
+### 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:
+
+```bash
+export 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](./get-started/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)